Where do displayed chapter titles come from?

[JJ Johnson]

I have some text file renderings of books that I'm running through a python script to break up into chapters and generate epubs. I'm just getting started, but so far, I break it up and format the content into chapter html files, generate container.xml and content.opf, then zip it up along with a standard css file. Still to do is to generate a table of contents and add a cover image.

When I load the epub (using calibre, which is converting to kepub) onto my Kobo Libra, it looks great, except that the chapter titles shown are the actual html filenames. In each hmtl file I have a <title> tag in the header (with "Chapter One", "Chapter Two", etc.), which is where I assumed it would get this data, but apparently not.

My content.opf is pretty simple, along with headers and metadata, it looks like:

  <manifest>
    <item href="chapter00.html" id="chapter00" media-type="application/xhtml+xml"/>
    <item href="chapter01.html" id="chapter01" media-type="application/xhtml+xml"/>
  </manifest>
  <spine>
    <itemref idref="chapter00"/>
    <itemref idref="chapter01"/>
  </spine

Does it require a toc? Or is there something additional I can add to the manifest items?

[jhowell]

Technically your book has no chapters so calibre is creating its own from the file names.

For EPUB 2 you need to create an NCX file. For EPUB 3 you need a navigation document, with NCX being an optional fallback.

[hobnail]

If you want to eyeball a well formed epub 2 or epub 3 you could use Calibre's editor or Sigil; I use the latter. Add an h2 at the start of each file. Then, in Sigil, use Ctl-T to generate a table of contents from the h2 tags. I prefer to make epub 3s so after I generate the table of contents, in Sigil's Tools menu I run the first two items in the Tools > Epub 3 tools menu; Generate ... and Update ... so that I get the optional fallback that jhowell mentioned. With Sigil you can have it start a new epub as either epub 3 or epub 2

[JSWolf]

Originally Posted by jhowell

Technically your book has no chapters so calibre is creating its own from the file names.

For EPUB 2 you need to create an NCX file. For EPUB 3 you need a navigation document, with NCX being an optional fallback.

The ePub 3 needs an NCX to be backwards compatible with ePub 2. So IMHO, if the ePub 3 is not using any specific ePub 3 features that would break with ePub 2, then an NCX is necessary.

[JJ Johnson]

Originally Posted by hobnail

If you want to eyeball a well formed epub 2 or epub 3 you could use Calibre's editor or Sigil; I use the latter. Add an h2 at the start of each file. Then, in Sigil, use Ctl-T to generate a table of contents from the h2 tags. I prefer to make epub 3s so after I generate the table of contents, in Sigil's Tools menu I run the first two items in the Tools > Epub 3 tools menu; Generate ... and Update ... so that I get the optional fallback that jhowell mentioned. With Sigil you can have it start a new epub as either epub 3 or epub 2

Looks like I have a bit more work to do than I thought. I take it, then, that chapter titles are typically displayed in H2 tags? Is that mostly just an Sigil/Calibre application convention, or part of some standard?

I'm using epub 3. I only have a need to ever view these books on my Kobo, so I'm not too worried about backward compatibility or publishing these books. So this is mostly an exercise in learning a bit about epub structure, and also a means of honing my python skills.

I'm still very fuzzy on the interplay between this navigation file, a TOC page, and the manifest and spine portions of the content.opf files. I'm sure I'll have more questions.

[hobnail]

Originally Posted by JJ Johnson

I take it, then, that chapter titles are typically displayed in H2 tags? Is that mostly just an Sigil/Calibre application convention, or part of some standard?

H2 is what I use. Sometimes books have Parts and I use h1 for those titles. You could just as easily use h5 for the chapter titles. The only convention that I know of is that Sigil nests the higher numbered h tags in the lower numbered ones; e.g., h2 is nested in h1. In the table of contents the nested ones are indented. When you generate the table of contents with Ctl-T you can specify which ones to include/use so I specify h2 and h1.

[JJ Johnson]

Originally Posted by hobnail

H2 is what I use. Sometimes books have Parts and I use h1 for those titles. You could just as easily use h5 for the chapter titles. The only convention that I know of is that Sigil nests the higher numbered h tags in the lower numbered ones; e.g., h2 is nested in h1. In the table of contents the nested ones are indented. When you generate the table of contents with Ctl-T you can specify which ones to include/use so I specify h2 and h1.

Is the 'table of contents' that you speak of Sigil generating the navigation document required of epub 3s, or is it a table of contents (x)html file? Or does it generate both?

[hobnail]

Originally Posted by JJ Johnson

Is the 'table of contents' that you speak of Sigil generating the navigation document required of epub 3s, or is it a table of contents (x)html file? Or does it generate both?

As per the epub3 specs the nav.xhtml file can be (and should be if I remember correctly) used for the navigation document as well as the displayed html table of contents. But sigil puts the nav.xhtml at the end of the epub. If you drag the nav.xhtml to just after the title page or wherever in Sigil's Book Browser it still shows up at the end on my Kobo Forma (I also make epub3s). If you drag in Calibre's equivalent then the displayed table of contents shows up where you dragged it to. Eyeballing the content.opf I saw that calibre deleted the linear="no" from the following line as soon as you drag the nav.xhtml anywhere:


<itemref idref="nav.xhtml" linear="no"/>

[DNSB]

Originally Posted by JJ Johnson

Looks like I have a bit more work to do than I thought. I take it, then, that chapter titles are typically displayed in H2 tags? Is that mostly just an Sigil/Calibre application convention, or part of some standard?

I'm using epub 3. I only have a need to ever view these books on my Kobo, so I'm not too worried about backward compatibility or publishing these books. So this is mostly an exercise in learning a bit about epub structure, and also a means of honing my python skills.

I'm still very fuzzy on the interplay between this navigation file, a TOC page, and the manifest and spine portions of the content.opf files. I'm sure I'll have more questions.

There are 6 header tags (h1 ... h6). My personal preference is to use h1 for books in a omnibus volume, h2 for parts in a single book and h3 for chapter headings. h4 get occasional use for sub-chapters. If I find myself wanting to use h5 and h6, it's time to step back and look at the way I'm structuring a book. Most renderers will display the ToC with indentation to indicate precedence.

h1
   h2
      h3
      h3
      h3
         h4
   h2
etc...

If for example, if I have <h3>Chapter x<h3> at the start of each chapter file, Sigil and calibre will generate the ToC document from those tags. I prefer using Sigil where it will generate the epub3 nav.xhtml document with the option to automatically generate the epub2 compatible toc.ncx file. OTOH, there are things that the calibre editor will do easier than Sigil so I keep and use both.

[JSWolf]

Most publishers use <p class="someclass">Chapter One</p> for the chapter title. But if you are wanting to make it easy to built a ToC from the chapter titles, use <h2>Chapter One</h2> and define what you want h2 to be in CSS.

[Turtle91]

Most Some publishers use <p class="someclass">Chapter One</p> for the chapter title....




....and I would add that although it is certainly possible to do it that way, I would recommend using the <h1-6> tags for their semantically correct purpose of providing a heading hierarchy. You can apply the exact same CSS to the <h> tags and visually it will be identical, but automated systems, accessibility systems, etc. can figure out the structure of your document much better/faster(/stronger??) if you use the proper markup.

It also has the added benefit of programs like Calibre or Sigil creating the automated ToC based on your <h> tags - as has been mentioned above.

[hobnail]

Originally Posted by Turtle91

Most Some publishers use <p class="someclass">Chapter One</p> for the chapter title....

A pox on those pusillanimous publishers.