EPUB: Links to anchors like #&&/2 cause a fatal error while parsing the file

[milmazz]

After checking the Elixir.epub file with epubcheck I got the following summary:

$ epubcheck doc/elixir/Elixir.epub --json elixir_docs.json

Check finished with errors
Messages: 9 fatals / 425 errors / 0 warnings / 0 infos

So, I will start listing here the issue with the highest severity, the one that's causing a fatal error while parsing the XHTML document.

Filtering a little bit the result with jq

$ jq '.messages[] | select(.severity=="FATAL") |{id: .ID, message: .message, locations: .locations | map({path, line, column})}' elixir_docs.json

We got the following:

{
 "id": "RSC-016",
 "message": "Fatal Error while parsing file: The entity name must immediately follow the '&' in the entity reference.",
 "locations": [
{
 "path": "OEBPS/Bitwise.xhtml",
 "line": 25,
 "column": 26
 },
{
 "path": "OEBPS/Function.xhtml",
 "line": 38,
 "column": 46
 },
{
 "path": "OEBPS/Kernel.SpecialForms.xhtml",
 "line": 67,
 "column": 20
 },
{
 "path": "OEBPS/Kernel.xhtml",
 "line": 116,
 "column": 38
 },
{
 "path": "OEBPS/anonymous-functions.xhtml",
 "line": 94,
 "column": 409
 },
{
 "path": "OEBPS/basic-types.xhtml",
 "line": 84,
 "column": 335
 },
{
 "path": "OEBPS/code-anti-patterns.xhtml",
 "line": 257,
 "column": 275
 },
{
 "path": "OEBPS/operators.xhtml",
 "line": 31,
 "column": 781
 },
{
 "path": "OEBPS/patterns-and-guards.xhtml",
 "line": 158,
 "column": 534
 }
 ]
}

When I started inspecting each of these files I noticed a pattern that matches with the error description of the entity name must immediately follow the '&' in the entity reference.

• anonymous-functions.xhtml -> <a href="Kernel.SpecialForms.xhtml#&/1">its documentation</a>
• basic-types.xhtml -> <a href="Kernel.xhtml#&&/2"><code class="inline">&amp;&amp;/2</code></a>
• Bitwise.xhtml -> <a href="#&&&/2"><code class="inline">&amp;&amp;&amp;/2</code></a>

So, the problem here in particular are the links to anchors like &/1, &&/2 and so on.

Why is this important?

In readers like Apple Books, you get the following warning at the beginning of the document:

And more importantly, once you reach the end of that document you will notice is truncated, at least if you compare that result with the HTML version:

Solution / Discussion

I'm putting this out there to start a discussion to see the approach we want to take for the EPUB formatter, I think we can first try changing those anchors from #&/1 to #&/1 and see if that works, otherwise, given that for the EPUB format the anchor name and links to it are all internal, we can change the anchor generation to be a hash instead.