Fragment identifiers
 

I am learning about the internals of the EPUB3 standard by writing my own transformation in XSLT2, using my thesis as an example text. Most of it is going excellently, but I am having some trouble understanding how the links between the toc.ncx and the documents are meant to work.

I am getting "ERROR: OEBPS/toc.ncx(25,47): 'd1e97': fragment identifier is not defined in 'OEBPS/index.xhtml'" (and others) from the online validator at ebookit.com for this:

21 <navPoint id="d1e97" playOrder="3">
22 <navLabel>
23 <text>Dedication</text>
24 </navLabel>
25 <content src="index.xhtml#d1e97"/>
26 </navPoint>

where index.xhtml says:

<div class="dedication" id="d1e97">
<p>To xxxx, yyyy, zzzz for their patience
and support.
</p>
</div>

Given that you are not allowed by EPUB3 to use <a name="..."> (the ebookit validator marks all occurrences of that as an error), what is the mechanism for the resolution of these links? What is the fragment identifier in line 25 supposed to point at? if not a name attribute on an <a> element, or an ID?

I don't know much about this, but it seems like you need full paths to files, or an indicator that is it relative to some other file.

But the index.html is in the same (OEBPS) directory of the .epub file as the toc.ncx, so I don't know how much fuller it can be.

fragments are NOT relative to the TOC (index.html), but to the file that contains the anchors id

#foo1 says in the same file
chapter1.html#foo1 says look in chapter1.html for foo1

The first case will get broken (in Sigils auto link rename) if the file splits from when the link was set

the second survives, thus the suggestion to always use full names. it is more robust (and easier to track down if it does get broken)

I have no idea what the validator for ebookit.com is based on on, but I know the gist of what you've posted is perfectly valid. Make sure you use the IDPF's validator (http://validator.idpf.org/) to eliminate any possibility that ebookit.com's validator is the culprit.

I've validated several epub3 documents where the (x)html file and the toc.ncx file were in the same directory. Same basic "index.html#frag" pointing to an element with the id="frag" syntax. It should work fine, so there must be something else wrong.

You don't actually need #d1e97 in line 25 since all you are doing is going straight to the beginning of index.xhtml. So just remove #d1e97 and any others like it and the errors will be gone.

How on earth can you possibly deduce from the code snippets provided that the link from the TOC can just go "straight to the beginning of index.xhtml" ? :blink:

Because index.xhtml is a dedication page. Other then the XML code that's not being displayed, it's complete codewise.

Why would you assume that index.xhtml is the dedication page only?

Wasn't the NCX file deprecated in EPUB3?

It still can still be included for various backward compatibility reasons. It will still pass the idpf's epubcheck with an ncx. But yeah, it's been replaced by the nav document.

Just got back to this...thanks everyone for the suggestions. I had assumed (duh) that because the IDs have to be unique across the documents, just the fragment identifier without the filename would work. Add the filenames and it's fine. The reason for fragment identifiers even when going to the top of the file was that the "top" isn't actually where I wanted to send users, it was one element down (just a matter of alignment).

Now I have a single XSLT2 program to generate all the files, plus a little script that extracts all the image filenames from figures, and copies them all into the epub directory, then zips everything up and creates the .epub file. Now comes the task of testing in all the common readers, and making something that Calibre can open and translate reliably to all the formats.

As you are doing your work, be aware that calibre's viewer is NOT guaranteed to display all possible varieties of epub3 and that if it does work, it may not in subsequent editions. It exists to support the other functions, not to serve as anybody's viewing platform.

Indeed not, but it makes a starting-point. I have a team of volunteers with different devices to do the hand-on checking.

Unfortunately, it looks that will be required from now on. There was some attempt toward working to spec for epub2, but for epub3, the device manufacturers aren't even trying, with Apple and Kindle not complying with anything.