Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

epub:type="toc" restriction #1292

Closed
VeryGoodErotica opened this issue Aug 28, 2019 · 12 comments
Closed

epub:type="toc" restriction #1292

VeryGoodErotica opened this issue Aug 28, 2019 · 12 comments
Labels
Status-Declined The issue has been reviewed and not accepted by the working group for inclusion

Comments

@VeryGoodErotica
Copy link

Hi, ePub spec only allows one nav element with epub:type="toc" and I am having trouble understanding why that restriction exists when there is historical precedence (e.g. the pulp magazines common in the 20s to 50s) to have multiple ToC with good reason.

My use case - I'm publishing a magazine. One ToC is called "Submission Fiction" and will contain user submitted stories.

One ToC is called "Thoughts and Prayers" and will contain poetry, essays, book reviews, etc.

One ToC is called "Eye of the Beholder" and will contain short interviews with glamour models along with some glamour photography of the model.

In the spine these are mixed, e.g. a poem and and glamour model interview will come between two stories and the then a book review. This at least was common in magazine publishing, hence the need for separate table of contents that make it easy for a reader looking for a specific item to find them. Example code:

<body>
<nav epub:type="toc" id="toc.ero">
<h1>Submission Fiction</h1>
<ol>
  <li><a href="AndiAliceBirthday.xhtml" class="tocmain">Alice’s Birthday Present</a><ol>
    <li><a href="AndiAliceBirthday.xhtml#E01.Anticipation" class="tocsub">Anticipation</a></li>
    <li><a href="AndiAliceBirthday.xhtml#E01.AliceAndSteve" class="tocsub">Alice and Steve</a><ol>
      <li><a href="AndiAliceBirthday.xhtml#E01.EatingStevesBologna" class="tocsub">Eating Steve’s Bologna</a></li>
      <li><a href="AndiAliceBirthday.xhtml#E01.TheMaidUniform" class="tocsub">The Maid Uniform</a></li>
    </ol></li>
    <li><a href="AndiAliceBirthday.xhtml#E01.TheNotebook" class="tocsub">The Notebook</a></li>
    <li><a href="AndiAliceBirthday.xhtml#E01.AndisGiftToAlice" class="tocsub">Andi’s Gift to Alice</a><ol>
      <li><a href="AndiAliceBirthday.xhtml#E01.AVisionOfBeauty" class="tocsub">A Vision of Beauty</a></li>
      <li><a href="AndiAliceBirthday.xhtml#E01.SelfControl" class="tocsub">Self Control</a></li>
    </ol></li>
  </ol></li>
</ol>
</nav>
<nav epub:type="toc" id="toc.ess">
<h1>Thoughts and Prayers</h1>
<ol>
  <li><a href="OriginSpecies.xhtml" class="tocmain">The Origin Species (poetry)</a></li>
  <li><a href="SubmissiveDevotion.xhtml" class="tocmain">Submissive Devotion</a><ol>
    <li><a href="SubmissiveDevotion.xhtml#ES01.Worship" class="tocsub">Worship</a></li>
    <li><a href="SubmissiveDevotion.xhtml#ES01.Dedication" class="tocsub">Dedication</a></li>
    <li><a href="SubmissiveDevotion.xhtml#ES01.Respect" class="tocsub">Respect</a><ol>
      <li><a href="SubmissiveDevotion.xhtml#ES01.SelfCare" class="tocsub">Self Care</a></li>
    </ol></li>
  </ol></li>
</ol>
</nav>
</body>

If I put both ordered lists into a single nav with their respective headers first, I get validation errors. If I take away the epub:type="toc" from the second nav I get validation error saying the nav must have that attribute.

Looking at the spec - it seems to define additional epub:type definitions that are useful for the academic world, like if you wanted a separate ToC for a list of tables or a list of figures, so why does the spec not allow for use cases like magazine publishing where different tables of contents for different types of content are sometimes used?

I guess I do not understand what problem limiting an ePub to only one epub:type="toc" solves, but the limitation certainly creates problems for ToC styles with historic publishing precedent.

Can we change the spec to allow more than one ToC?
@dauwhe
Copy link
Contributor

dauwhe commented Aug 28, 2019

A major problem is that reading systems use this information to construct their built-in navigation. I am not aware of any reading system that can display two separate built-in primary navigation structures.

It's totally acceptable to create a nested TOC. The top level could just contain the two headings mentioned above.

@mattgarrish
Copy link
Member

The top level could just contain the two headings mentioned above.

But in this case, I think the next problem is that it runs afoul of the all entries must be ordered rule we're discussing... ;)

@dauwhe
Copy link
Contributor

dauwhe commented Aug 28, 2019

But in this case, I think the next problem is that it runs afoul of the all entries must be ordered rule we're discussing... ;)

Coded as ol/li, of course :)

@mattgarrish
Copy link
Member

And sure enough: #1283 (comment)

@VeryGoodErotica
Copy link
Author

If the purpose is for machine parsing, would an optional separate file for machines to parse be a better solution?

I suppose I could make a single OL and use CSS to display the top order the same way h1 headings are displayed to get the same effect, but that CSS would get pretty complex and lose the simplicity of separate lists in their own nav group with their own heading.

@dauwhe
Copy link
Contributor

dauwhe commented Aug 28, 2019

If the purpose is for machine parsing, would an optional separate file for machines to parse be a better solution?

We tried that with the NCX file in older versions of EPUB, which was based on an entirely separate XML vocabulary. The nav file was designed to be both human- and machine-readable, hence the content restrictions. Working on some test files right now.

@mattgarrish
Copy link
Member

If the purpose is for machine parsing, would an optional separate file for machines to parse be a better solution?

We tried that with the NCX file in older versions of EPUB, which was based on an entirely separate XML vocabulary. The nav file was designed to be both human- and machine-readable, hence the content restrictions.

But if these are only for the content, don't use the navigation file if its rules are too troublesome. You can just put them in a regular content document in the spine. It's only a convenience that the navigation document can be used for both purposes.

You will still have to provide a navigation document with a toc for reading systems, though, as it's part of ensuring feature consistency.

@VeryGoodErotica
Copy link
Author

Something like this for readers to use that could be a separate file or part of the .opf but is not intended for display as a page - it could have the spine order requirement.

<ReaderTOC>
  <item href="AndiAliceBirthday.xhtml"                         level="article">Alice’s Birthday Present</item>  
  <item href="AndiAliceBirthday.xhtml#E01.Anticipation"        level="section">Anticipation</item>
  <item href="AndiAliceBirthday.xhtml#E01.AliceAndSteve"       level="section">Alice and Steve</item>
  <item href="AndiAliceBirthday.xhtml#E01.EatingStevesBologna" level="subsection">Eating Steve’s Bologna</item>
  <item href="AndiAliceBirthday.xhtml#E01.TheMaidUniform"      level="subsection">The Maid Uniform</item>
  <item href="AndiAliceBirthday.xhtml#E01.TheNotebook"         level="section">The Notebook</item>
  <item href="AndiAliceBirthday.xhtml#E01.AndisGiftToAlice"    level="section">Andi’s Gift to Alice</item>
  <item href="AndiAliceBirthday.xhtml#E01.AVisionOfBeauty"     level="subsection">A Vision of Beauty</item>
  <item href="AndiAliceBirthday.xhtml#E01.SelfControl"         level="subsection">Self Control</item>
  <item href="OriginSpecies.xhtml"                             level="article">The Origin Species (poetry)</item>
  <item href="SubmissiveDevotion.xhtml"                        level="article">Submissive Devotion</item>
  <item href="SubmissiveDevotion.xhtml#ES01.Worship"           level="section">Worship</item>
  <item href="SubmissiveDevotion.xhtml#ES01.Dedication"        level="section">Dedication</item>
  <item href="SubmissiveDevotion.xhtml#ES01.Respect"           level="section">Respect</item>
  <item href="SubmissiveDevotion.xhtml#ES01.SelfCare"          level="subsection">Self Care</item>
</ReaderTOC>

@dauwhe
Copy link
Contributor

dauwhe commented Aug 28, 2019

Keep in mind that we have a quite mature specification that's widely implemented. I just created an EPUB with two nav epub:type="toc" and a popular reading system only displayed the second nav.

I would much prefer to tweak the nav content model (if it proves necessary) than invent an entirely new XML format. We have a little too much experience with the latter ;)

@VeryGoodErotica
Copy link
Author

I suppose it also has to work with Amazon's tool that converts ePub to their proprietary format. I don't like proprietary formats but authors have to sell on their platform, eating is nice.

@VeryGoodErotica
Copy link
Author

Okay I found a solution that "works for me" at least in Calibre

One single <nav epub:type="toc"></nav> that has a single OL in the spine order but my css has

nav {
  display: none;
}

Then I have <section class="nav"></section> for each of the ToC that I want users to see, they display as intended and serve the purpose or user selection while allow the nav that isn't displayed to serve the purpose of the users.

Maybe some readers won't respect the display:none; CSS - I don't know - but that's not the end of the world.

I think my use case is edge enough that this workaround is sufficient. So I'm going to close.

@VeryGoodErotica
Copy link
Author

I suppose I probably should add a role="navigation" to those section nodes, I still have to look at ePub a11y and see how it compares with html5 a11y best practices.

@danielweck danielweck mentioned this issue Aug 28, 2019
Closed
@mattgarrish mattgarrish added the Status-Declined The issue has been reviewed and not accepted by the working group for inclusion label Sep 14, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Status-Declined The issue has been reviewed and not accepted by the working group for inclusion
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@mattgarrish @dauwhe @VeryGoodErotica