Tables of Contents Revisited

Alas… I don’t think I can say I learned while working on the best practices book that no matter how detailed you think you’ve reviewed your prose, some flubs will make it through.

Only because I learned that lesson a long time ago when I first got into publishing. I’ve seen notes from an author to an editor in a final print run, after all. (Thankfully, the editor wasn’t me!)

It doesn’t surprise me, then, that some errata has been noted, or that I’m the one reporting some of it. You can only hope that your mistakes are small, and the errata haven’t been all that critical to date.

That said, when you make an error, there’s no point running from it, and the two bits of errata that most bother me are both in the navigation chapter. I just gave a brief synopsis of one of the issues in the IDPF forums, so I figured I’d take a little more time to outline them both here.

And maybe take a look at a couple of additional clarifications we tried to make during the 3.0.1 revision, as grasping the in-spine and out-of-spine uses is proving to be generally confusing.

In-spine v. Out-of-spine

Before we can get anywhere in this discussion, it bears a quick explanation of the dual-use nature of the navigation document for anyone who hasn’t read the free preview chapter. (Shame on you if you haven’t!)

If you’re familiar with EPUB 2 and the NCX, you’re familiar with out-of-spine rendering of the table of contents. The NCX enabled the creation of custom interfaces in the reading system. Click the table of contents button on your device or app, and up comes the list of links generated from the information in the NCX. This is out-of-spine rendering.

You couldn’t include the NCX in the spine, so EPUB 2 had no concept of dual use. If you wanted a table of contents to follow your cover image as the reader progressed through the book, for example, you had to include a separate XHTML content document in the spine.

The EPUB 3 navigation document blurs the distinction between reading system-defined presentation of the table of contents and regular content in your book, as the navigation document is both a content document and declarative markup.

As such, the navigation document is always used to create the custom reading system view, but can also be included as a content document in the spine.

But this dual use makes it more complicated to figure out what’s supposed to happen in what rendering, which is where ambiguities arise…

When is out-of-spine out of the spine?

This is one of the real head scratchers.

After reading the previous section, you probably have a firm grasp that one rendering is provided by the reading system, unrelated to what is in the spine, and the other rendering is plain old XHTML in the spine. That’s the easy part. Here’s the twist: out-of-spine rendering doesn’t mean a special pop-up widget has to be displayed.

In fact, the reading system can, for its custom view, render your navigation document like it’s a regular XHTML document in the content area. Confusing, right?

The bigger twist is that it doesn’t have to render the navigation document as it would if it were in the spine. It’s free to strip any styling you’ve defined, for example. It could even strip everything that’s outside the nav elements.

Why would a reading system do this? The primary reason would be to provide a consistent look-and-feel across books. Just because the document is being rendered as XHTML, doesn’t mean it should look like you styled it. By applying its own styles, it can use the information you provided, but present it as a custom interface.

The takeaway is that reading systems own the presentation out of spine, no matter how they render it. You only have control over the rendering of the version you place in the spine, as in that case it’s just another XHTML document.

I’ll come back to this distinction again as we go.

Hiding Content

At this point, I’ll turn to one of the inaccuracies in the book.

In the navigation chapter, I point out that how the HTML5 hidden attribute is used to hide branches of the table of contents. It can also be used to hide individual list items, if you want, but without a real-world use case for why someone would do that, I didn’t bother to outline it in the book.

In reformulating the NCX as XHTML during the 3.0 revision, and adding the hidden attribute to hide branches, my understanding had always been that it was a method for collapsing branches in the out-of-spine view. I’d taken away from the discussions that people were stripping down the NCX because there was no way to control the reading system-generated view. Rather than deal with runaway nesting, the hidden attribute could be used to reduce what was visible by default, encouraging producers not to strip down the table of contents, which reduces the navigability for anyone using an assistive technology.

While the above might make sense, my assumptions were just those.

I began questioning this interpretation after re-reading the navigation document section of the Content Documents specification, as it only talks about the hidden attribute lacking any meaning outside the spine, so opened a bug to figure out what the intent actually was.

The result was a clarification that ignoring hidden attributes was a means of allowing a reduced table of contents in the spine without requiring the full table of contents be stripped for out-of-spine rendering. Basically a flip of my understanding, but with a similar goal of the out-of-spine rendering not missing entries.

Despite my beliefs, the requirement spelled out in the specification is only that reading systems have to ignore the hidden attribute for out-of-spine rendering. Another instance of the author not having influence on the out-of-spine rendering.

A reading system is consequently not expected or required to collapse branches based on the use of the hidden attribute. I still contend it misses a need, but maybe that’s just me being stubborn.

What does this mean if you’ve followed the guidance of the book? Only that a reading system will show all the branches in the out-of-spine rendering, which I suggested was not the case (although there’s nothing to say the reading system can’t use the attribute as a hint for collapsing branches; it’s just not required and I’m not aware of any that do).

More pointless is the discussion about removing hidden attributes by script for in-spine rendering. Since that’s the only place where using hidden matters, there’s no reason why you would ever strip them.

Try to pretend I didn’t write any of that, if you can.

Mea culpa, but hopefully you can forgive me this one.

Out-of-spine customizations

To return to what you can expect a reading system to do with your table of contents out of the spine, there are only two requirements beyond providing access to the links:

  1. Ignore any use of the hidden attribute in the nav elements.
  2. Not render any list numbering.

After those requirements, the specification doesn’t go into any detail about what the reading system has to do with the table of contents when presenting it outside the spine. In addition to ignoring styles and surrounding content, as I wrote above, a reading system can:

  • ignore all tags you use within the links;
  • disable all scripts.

Yup, any inline tagging — like emphasis, superscripting, subscripting and ruby — does not have to be rendered as such. The only requirement is to present the text label as the link.

Of course, these are bare minimums, so don’t take the ability to ignore your inline tags as a requirement.

I’m just trying to pound home the notion that the way you want the document to look in the spine is irrelevant outside the spine.

What to do…

So where does that leave you?

I’d still suggest using the navigation document for dual purposes if you’re not trying to do anything fancy for in-spine presentation. So long as your table of contents is just a plain old list of links, you probably don’t have a lot to worry about in terms of things breaking.

It’s only when you start to adorn your contents (think of all the information that often surrounds the table of contents in textbooks), disable links, script the document and do other funky things like that that you run the risk of cross-reading system inconsistencies.

And it’s still hard to say how big a problem this will be, but evidence suggests that some mix of custom widgets and XHTML rendering has to be expected.

If you really want to do something fancy with the table of contents, it may just be better to derive a new document from the basic table of contents in the navigation document and keep the two uses separate. It defeats the purpose of the navigation document to some extent, but it’s perfectly legal to do.

Inactive links

To wrap up, I said there were a couple of misstatements in the chapter, so I’ll quickly note the other less bothersome one (to me).

I suggested that inactive links could not be accommodated, which is only kind of true, and only to the extent that it’s unclear what removing href attributes from a elements will do to reading systems.

Technically speaking, this is a perfectly valid inactive link in the table of contents:

<li><a>Chapter 2</a></li>

But have a look at the previews post I did a few days back for more information on options now that there is a formal specification for doing previews. Both linking methods mentioned there would also work for incremental releases of an EPUB.

Now that I have those little sins off my chest, maybe I’ll sleep a little better… ;)

Leave a Reply

Your email address will not be published. Required fields are marked *