Publishing Technical Documents with ePub

Prerelease Version

Footnotes, References, and Indexes

Footnotes and other internal links, if handled correctly, can add a great deal to your content. But if handled badly, they can interrupt the flow of your document and confuse your reader. This is especially true for ePubs which, unlike printed documents, have no footers for you to place your footnotes in.

Footnotes

The ePub 3.x spec has a number of additions that make it much easier to handle footnotes. The official recommendation is to use ePub 3.x structural semantics (listed here) to indicate that an internal link is referring to a kind of footnote. Note: you will need to declare the epub namespace in your root html element (<html xmlns:epub="http://www.idpf.org/2007/ops">), otherwise you may have issues with parsing and validation.

The content you link to should then be placed in an <aside> element with the appropriate structural attribute to added to indicate whether it is a footnote, and endnote, or some other kind of note.

Example Footnote

<p>Here is an example footnote<sup><a epub:type="noteref" href="#n1">1</a></sup></p>

<aside epub:type="footnote" id="n1"><p>With a footnote here.</p></aside>

And the result should look like this1.

There are ways to mimic this behavior for ePub 2.x content, but they aren’t as clean as the 3.x specification.

References/Endnotes

How you handle this kind of content depends on how you plan on styling your document. You will need to use links to navigate to your end section. However, if these links are in a separate content file in your ePub, you likely should not mark them up using <aside> elements as that is not semantically appropriate. You should, however, include a backlink to take your reader to the original location in the text. If you decide to collect all of the end notes at the end of your file, you likely should use an aside, but with epub:type="rearnote" instead [2].

This can be a problem to keep track of, and if at all possible, you should try to use a system that automatically generates these links. We will cover some of these in a future chapter.

Example Endnote

<p>Here is an example endnote<a epub:type="noteref" href="#n2" id="fn-ref2">[2]</a></sup></p>

<aside epub:type="rearnote" id="n2"><p>Example endnote. <a href="#fn-ref2">&#160;&#8617;</a></p></aside>

Indexes

Not all works require an index, but it can be very helpful to have one. Again, you run into the differences between ePub and print as the page numbers in a reflowable ePub are not fixed, which makes indexes a little more tricky.

An index will likely need to be in a separate content file from your main text. This means that, in addition to pinpointing the location of each entry in the text, you will also need to know which containing .xhtml file you are looking at if you want to create a working link.

While it is possible to use some kind of search and replace to add location anchor for each entry, that does add alot of markup to your file. One recommendation, from Liz Castro’s excellent blog, is to add anchors to your markup at the end of each page in a printed copy, and use those anchors as reference points for your index (this is the pageList feature mentioned here).

If you don’t have a physical copy to work from, you could add reference points to headers, sections, or other places in the text and have your index refer back to these points. This is still a much better solution then adding a new reference point for each index entry.

Note on creating an index: The good thing about electronic files is the ability to search all of your content for the existence of a potential index term. However you can go overboard with this. So try to only include entries that are helpful, rather than just a passing mention. Using a header or other type of signpost should also help you to avoid adding multiple entries that are too close together.

Looking Ahead

We’ve covered the ePub format in detail. You should now have some idea about how to build an ePub document with technical content using nothing more than a text editor and some command line tools. But handcrafting ePub documents is not the workflow of choice for most of us. The rest of the book will look at different tools for managing and automating your workflow.

Previous

Next

Table of Contents