6.2 | Section Labels

Here we go a bit more in depth on why these labels are added at the start of each section of e-book content. This has to do with Table Of Contents creation and tricking Sigil into doing some heavy lifting for us.

The following explanation might confuse the crap out of some users. Sorry. But there is a method to all this madness. 

We add these labels now so that later on, those labels can have HTML header tags like <h1></h1> or <h2></h2> applied to them.

Still later, when Sigil creates projectx's Table Of Contents for us, Sigil looks for those <h1></h1> or <h2></h2> header tags. Whatever text appears between those header tags like "Title" and "License" is captured as a Table Of Contents entry. Those captured labels become listed as pages in the Table of Contents.

Later still, we remove the actual Title and License header labels but not the <h1></h1> tags from the e-book code. The text is replaced with a non-breaking space's HTML name ( &nbsp; )

This bait-and-switch method leaves the Table of Contents entry (like Title or License) intact, but removes those labels from the actual page that displays on an e-reader or e-book app. 

Basically, we've created an invisible header.

This is done to save a ton of busywork. It's lazy, but it works.

WARNING:

The tutorial puts Table Of Contents creation at a point quite late in the production process. A lot happens to those labels before we reach that point.

At one specific point, the label text is replaced in the e-book code with &nbsp; (the HTML name for a non-breaking space). This step removes the label text from the page, but leaves the TOC (table of contents) label entry intact.

Trouble never happens... unless the user has to, for whatever reason, regenerate the TOC.

If, after that non-breaking space has been substituted for the label, the user has to regenerate the TOC, guess what happens? Sigil goes looking for those <h1></h1> or <h2></h2> tags again and slaps whatever it finds between those tags into TOC as entries. So now those users will have what appears to be blank entries in their TOC in place of Title and License because Sigil thinks &nbsp; is what's supposed to be there.

It's quite possible to fix this in Edit Table Of Contents, but that's sort of jerry-rigging things and doesn't get to the core of the issue for tutorial users, so here we'll learn what actually determines what text appears in that TOC listing.

Fixing this problem requires a trip into the EPUB's toc.ncx file. The toc.ncx file can be found near the bottom of the Book Browser pane.

Figure 3: The graphic below was borrowed from a different section, but what's shown pertains to this labels issue: A blank TOC entry (shown by purple arrows at far right side) is fixed by altering what appears between its corresponding <text></text> tags in its navPoint entry (highlighted by a red rectangle).

In EPUB, a navPoint is created for each heading or anchor created in the file's content. If you really look at the figure below, you can see <navPoint></navPoint> sections in the code. Inside those navPoint tags is <navLabel></navLabel>. There is also a content source line showing which file contains this navPoint.

Focus on the navLabel tags. Inside those we find a pair of <text></text> tags. Whatever text appears between those two tags is the text that appears as the TOC entry. 

Wherever empty text tag-pairs appear, (or if &nbsp; appears between those tags) a blank TOC entry appears, and vice versa. 

To repair TOC text mishaps, this is where it's done. Simply type the desired text between those <text></text> tags and watch Sigil update that TOC pane for you. What you won't see are changes to the content.opf file, but that's a whole other can of worms I just refuse to open.

Sorry if you're sorry for clicking into this supplement.

Return to "Gather Content"