Can Everton Jones find out how his father stole Emperor Bokassa’s diamonds and, more importantly, where he hid them; before the world and his brother get there first?
Click on the picture link in the sidebar to read an extract of my first novel, which was published by Paradise Press in August 2012.

Thursday, 3 July 2014

How to generate the logical table of contents using Sigil

The logical table of contents in an e-book is a file called toc.ncx. Sigil generates this for you and I strongly recommend against trying to do it for yourself. The e-reader uses toc.ncx to build a table of contents which is usually displayed by pressing some sort of button on the e-reader or else by selecting a choice from a menu. (See images below) It is quite separate from the html table of contents. Every e-book HAS to contain a logical table of contents, so that an e-reader which is set up to access it (and that is most if not all of them) can do so. Your e-book will FAIL epubcheck and kindlegen if it does not have an ncx table of contents.

This post is somewhat out of sequence. You will need to have completed the end matter before you generate the table(s) of contents. But, as the linking and styling of the end matter is considerably more complex than for the front matter and main text, I will deal with all of that later. (See my posts on how to do endnotes, a bibliography and an index which have now been published.)

At its simplest, an e-book will most likely just consist of a linear sequence of chapters. To build the logical table of contents using Sigil, you NEED an <h1> (main heading) tag at the start of each chapter, enclosing the chapter heading.

Generating toc.ncx in a basic e-book:

I am going to start with a simple example to show how Sigil uses the <h1> tags to make the logical table of contents.

Chapter one in a basic e-book might look like this in code view:

<body>
   <h1>Chapter One</h1>
   <p
>It was a dark and stormy night</p>
  

</body>


I have replaced unnecessary detail with an ellipsis (…).

The main point is that EACH chapter you want included in the table of contents should begin with an <h1> tag. Once you have edited these into your ebook, click the ‘Tools/Table of Contents/Generate table of contents …’ menu item in Sigil:




A dialog loads with all the <h1> tags listed:


Notice the check boxes to the right. Uncheck an item to leave it out of the table of contents.

NB Generally the default settings for the dialog should be sufficient. But they can be changed. There is a dropdown menu at the bottom left of the dialog which allows you to select which headings are included in the list to begin with. Above that dropdown menu there is a checkbox. If: ‘show TOC items only’ is checked, the list in the dialog will only show headings which you have decided to include in the toc. With this option set, unchecking an item in the list will cause it to vanish completely!


Once you have selected the headings to include in the logical table of contents, just click ‘OK’ at the bottom right of the dialog to generate it. When Sigil has finished, if it was not already visible, the table of contents window should open, showing each chapter title:


You can, in fact, use the table of contents window to navigate around your e-book. Clicking ‘Chapter One’ takes you to the start of Chapter One, etc. Note that the text displayed in the Table of Contents is whatever was entered inside the <h1> tags, NOT the corresponding filenames.

What Sigil has actually done is to create (or rather update) the file: ‘toc.ncx’. The syntax of toc.ncx is very complex, and it is strongly recommended to use Sigil to generate it. toc.ncx will have been correctly linked in the manifest and spine sections of content.opf and you need do nothing else. The logical table of contents will work properly.

[If your e-book is divided up into parts, each with its own part title page, then use an <h1> tag for the part titles and an <h2> tag for the chapter titles. Provided these tags constitute the first line in the body of the relevant file, the method above is sufficient. Use lower-level <h> tags for sub-headings etc.  but, as these fall within the chapter, a slightly different approach has to be followed. See below.]

What to do if you are following my methods:

If you have been following my method, your chapter might have looked like this to begin with:

<body>
  <p class="chapterHeading">Chapter One</p>
  <p
>It was a dark and stormy night</p>
  

</body>


In this case you would want to add an <h1> tag duplicating the <p> tag:

<body>
   <h1>Chapter One</h1>

   <p class="chapterHeading">Chapter One</p> 
   <p>It was a dark and stormy night</p>
  

</body>


Following my method, your stylesheet would make the <h1> tag invisible with the following in the CSS stylesheet:

h1 {display: none;}

Then you would follow the procedure above to generate the logical table of contents, toc.ncx.

An alternative to making the <h1> tag invisible is to generate the logical table of contents and then delete the <h1> tag entirely. PROVIDED you do not attempt to re-create the table of contents, this should be alright.

Whatever you do, DO NOT rely on CSS to style the <h1> tags. Some e-readers seem to impose their own styling on these tags and, I strongly suspect, on the other <h> tags as well. Either delete them or make them invisible and rely on a <p> tag and CSS styling to display the heading and you can’t go wrong.

The above assumes that the <h> tag is the FIRST html tag following the opening <body> tag in the chapter. If your e-book (as is most likely) only consists of a linear sequence of chapters, like in the example above, you are now all done. Click here to skip the next bit.

Including Subheadings in the table of contents in a simple e-book:

If you have subheadings in your chapters, and want to include them in the table of contents, you will need to read on.

I should point out that Sigil left the <h1> tags in each of the actual chapters completely unchanged when it built the logical table of contents. FOR the record, here is the entry for the first chapter in toc.ncx:

<navPoint id="navPoint-1" playOrder="1">
   <navLabel>
     <text>Chapter One</text>
   </navLabel>
   <content src="Text/Chapter1.xhtml" />
</navPoint>


I explain the ncx table of contents in detail in my next post but note here that the <text> tag encloses the text which will be displayed in the table of contents. Sigil has entered just what was enclosed by the <h1> tag in the chapter. And note also that in the <content/> tag the src is Text/Chapter1.xhtml which is the filename and path to the file containing the chapter: Chapter1.xhtml. The item: playOrder is a hang-over from the original purpose of the specification for the ncx: as an index for audio books!

That is exactly as it should be and you need do nothing at all with it. If you have only got a linear sequence of chapters with no subheadings, Sigil does all the hard work for you. The file: toc.ncx will be correctly linked in content.opf and will work properly.

BUT if your e-book has subsections in the chapters, you will need to use <h2> tags for these, to flag them up to Sigil as subheadings. For instance you might have something like this (simplified version):

<h1>Monday</h1>
<p>It was a dark and stormy Monday
</p>
<h2>Morning</h2>
<p>It was a dark and stormy morning
</p>

[For sub-sub-headings, use an <h3> tag and so on.]

[If you have part title pages, use <h1> tags for these, <h2> tags for chapter headings, <h3> tags for any sub-headings and so on.]

Once all the <h2> etc. tags have been included in your e-book, follow the procedure above to generate the table of contents.

In this case the Generate Table of Contents dialog will look something like this:



Selecting the ‘Subheading’ line and clicking on the left arrow button:



will change the subheading back to a main heading (<h1>), much as using the tools in Outline view in Microsoft Word will do for a print book file. And the right arrow button will change it to an <h3> heading. Likewise clicking on ‘rename’:


will allow you to rename the entry. Corresponding changes to the tag type and/or content will be made by Sigil in the chapter. Handy though this is, if you have a finished e-book on your hands this feature will probably not be of much use.

What to do about subheadings if you are following my methods:

If you have been following my method, YOUR e-book chapter complete with subheadings might actually have looked like this when you began building the ncx table of contents:

<p class="chapterHeading">Monday</p>
<p>It was a dark and stormy Monday
</p>
<p class="chapterSubHeading">Morning</p>
<p>It was a dark and stormy morning
</p>

You will need to edit in some <h1> and <h2> tags duplicating the <p> tags:

<h1>Monday</h1>
<p class="chapterHeading">Monday</p>
<p>It was a dark and stormy Monday
</p>
<h2>Morning</h2>
<p class="chapterSubHeading">Morning</p>
<p>It was a dark and stormy morning
</p>

Style <h> tags which fall at the beginning of chapters to be invisible, following the method above. But don’t do anything about <h2> etc. tags which fall within the text. See below for how to deal with these.

Now follow the method above to generate toc.ncx.

I used an example with a single subheading in chapter 2 (see above). When I was done, the Table of Contents pane in Sigil looked like this:



Going back to Chapter Two, you will see that in this case Sigil has edited the <h2> tag in the chapter to include the following label: id="sigil_toc_id_1":


Sigil has added this label to mark a place in the file for the e-reader software to jump to when the item in the .ncx table of contents is clicked. The filename alone is now no longer sufficient.

And in toc.ncx the label: id="sigil_toc_id_1" has been used to build the src in the <content/> tag:

<navPoint id="navPoint-3" playOrder="3">
  <navLabel>
     <text>subheading</text>
  </navLabel>
  <content src="Text/Chapter2.xhtml#sigil_toc_id_1" />
</navPoint>


src="Text/Chapter2.xhtml#sigil_toc_id_1" is the location of the label in the <h2> tag created by Sigil and this entry in toc.ncx tells the e-reader to jump to that location when the link is clicked.

Now this is all very well and you can probably live with what Sigil has done. BUT that label: id="sigil_toc_id_1" isn’t very informative and, if you are going to delete the <h2> tag anyway, something has to be done. You will also need to reference the label when creating the HTML table of contents, so having a machine-generated label is a right old nuisance. What you need is something more user-friendly.

My strong recommendation is to do the following ONCE you have built the logical table of contents:

EITHER, in a simple e-book, REPLACE the <h2> tags entirely with <p> tags styled using CSS:

i.e. change the entry in the chapter from: <h2 id="sigil_toc_id_1">subheading</h2>
to: <p class="chapterSubHeading" id="my_meaningful_id">subheading</p>

OR, following my method, edit the <p> tags to include a meaningful label.

i.e. change them from: <p class="chapterSubHeading">subheading</p>
to: <p class="chapterSubHeading" id="my_meaningful_id">subheading</p>


and then delete the <h2> tags entirely

AND THEN: in both cases change the entry in toc.ncx 

from: src="Text/chapterfilename.xhtml#sigil_toc_id_1"
to: src="Text/chapterfilename.xhtml#my_meaningful_id"

NB class="chapterSubHeading" applies the styling you want using CSS to the sub-heading.

As I have said elsewhere, please use single text strings with NO SPACES for the labels and filenames and make sure the labels used to identify each subheading are unique. The text displayed in the chapter CAN be repeated but the LABELS should each be different (at least within the same chapter). And MAKE SURE THE LABELS MATCH in the chapter and in toc.ncx. Remember they should be single text strings with No SPACES and are CAse SEnSiTIvE!

Provided you do not try to re-generate the table of contents using Sigil this approach should cause no problems. If in doubt, edit the files using KomodoEdit instead. (see my post on how to do this here)

And now, finally, looking at the entries in toc.ncx for the WHOLE of chapter Two in this example:

<navPoint id="navPoint-2" playOrder="2">
  <navLabel>
    <text>Chapter Two</text>
  </navLabel>
  <content src="Text/Chapter2.xhtml" />

  <navPoint id="navPoint-3" playOrder="3">
     <navLabel>
       <text>subheading</text>
     </navLabel>
     <content src="Text/Chapter2.xhtml#sigil_toc_id_1" />
  </navPoint>

</navPoint>


You will notice that following the first <navpoint> tag instead of a closing </navpoint> tag there is another opening <navpoint> tag. This IS closed by </navpoint>, followed by the missing closing </navpoint> tag.

In other words, the subheading is NESTED inside the heading in the ncx. It is a hierarchical table of contents. When the ncx is displayed by the e-reader, depending on the particular device, it will be set off in some way, most likely by being indented on the left. Sigil has taken care of this for you.

You will now have a working toc.ncx correctly linked in content.opf.

IMPORTANT: If you have styled any of the <h> tags to be invisible, you will have to delete them when you convert your epub to a kindle, as the Kindle will ignore a display property with a value of ‘none’.

Implementation on a Sony E-Reader:

Going to my aged and trusted Sony E-Reader, I opened the e-book I have been using as an example. Clicking the ‘options’ button and then navigating the menu: clicking : ‘Go To’ and then ‘Table of Contents’:

brings up the logical table of contents, built by the e-reader using toc.ncx:


The scans are a bit out of focus, because the e-reader screen couldn’t be perfectly flat on the scanner glass, but you can see, in the case of the Sony e-reader, the chapters with sub-sections are displayed with a distinctly different icon and a ‘left arrow’ at the end of the table of contents item, indicating there is more to be seen by clicking on it. And indeed, clicking on any of these chapters opens the item to display the sub-sections within it:


This is how the Sony e-reader software copes with toc.ncx.

Implementation of toc.ncx on the Kobo:

Other e-readers will do it differently. For instance this is how the logical table of contents appears on the Kobo. (Note that the Kobo hasn’t indented the subheadings. This was decided by whoever programmed the Kobo and you have no control over this):



Comparison with the html table of contents:

However, navigating to the html table of contents, which YOU have designed and which is quite separate from the logical table of contents, will always display in the same way as it is part of the text of the e-book. Here are the html tables of contents on a Sony, Kobo and Kindle side-by-side, for comparison:


Next Step: You are now ready to generate the HTML table of contents. My next post will be a reference to the syntax of toc.ncx.

Index to ‘how to …’ posts:

How to ‘unpack’ an epub file to edit the contents and see what’s inside.
How to understand what is inside an epub
How to link the html table of Contents in a Kindle e-book
How to restructure the html table of contents for a Kindle
How to delete the html cover for a Kindle ebook
How to link the cover IMAGE in a Kindle e-book
How to clean up your MS Word file before your get started
How to markup an MS Word file to identify the formats before importing it into an epub
How to create a new blank e-pub using Sigil
How to import your marked-up MS Word file into your ebook using Sigil
How to create and link a CSS stylesheet in an e-book using Sigil
How to replace the markup with CSS styles in your ebook using Sigil
How to style an e-book so it works with the limited CSS styling available to Kindle e-readers
How to understand the syntax of CSS
How to style Small Caps in an e-book
How to split your ebook up into chapters using Sigil
How to sequence your e-book
How to phrase the copyright declarations etc. in an e-book
How to generate the logical table of contents using Sigil
How to understand toc.ncx in an e-book
How to generate the html table of contents in an e-pub
How to style the html table of contents using CSS
How to create an html cover for your epub using Sigil
How to present references and notes in a book
How to use Mark Up to link notes in your e-book
How to present a bibliography in a book
How to use markup to link entries in a bibliography with the notes section
How to index an e-book
How to use the tools in MS Word to create an index
How to alphabetise an index or bibliography

TinyURL for this post: http://tinyurl.com/muoh993

3 comments:

  1. Why do you add the css to make h1 invisible if you're just going to delete them before converting to mobi?

    ReplyDelete
  2. I put in the chapter headings at the beginning of the seven chapters - hit compose table of contents, a window came up as you suggested with NO entries. There's no way to add entries. It just sits there. I did something wrong but there's nothing in this program telling you what. help?

    ReplyDelete
  3. AND NEVER MIND i figured it out - the h1 tags are never manually inserted - use the h1 buttons on the left to do it

    ReplyDelete

 
Twitter Bird Gadget