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.

Wednesday, 5 November 2014

How to understand the spine and guide in content.opf

Content.opf is the most important part of an e-book. This is my final post about this file, covering the <spine> and <guide> portions. The <manifest> is detailed here, the <metadata> is covered in this post (including how to use the metadata editor in Sigil) and the sequence begins with an overview here.

The spine is found between the opening <spine> tag and the closing </spine> tags in content.opf.

Entering the ncx table of contents in the spine:

Firstly, note the opening <spine> tag:

<spine toc="ncx">

The ncx table of contents MUST be referenced in the opening spine tag exactly as shown above, using the spine toc attribute. Like all other items in the spine the ncx table of contents is referenced in the spine by the id assigned to it in the <manifest>. In this case Sigil by default uses an id="ncx". I can see no logical reason in the specification why that particular id should be mandatory and I would have thought any other id would do, provided it matches in the opening <spine > tag and in the <manifest>. However I cannot see any good reason for NOT using it either. Sigil does it this way automatically and it works and follows the example in the specification, so why change it? See here in my earlier post about the <manifest> for more information about how Sigil labels the ncx.

Syntax of the Spine:

The spine part of content.opf is essentially just a list of the items in the e-book which are to be displayed in order. Each item in the spine is referenced by the id given to the item in the manifest. So a typical spine would look like this:

<spine toc="ncx">
   <itemref idref="Cover.xhtml" />
   <itemref idref="Contents.xhtml" />
   <itemref idref="Chapter1.xhtml" />
   <itemref idref="Chapter2.xhtml" />
   <itemref idref="backCover.xhtml" />

The spine consists of a series of <itemref /> tags, one per xhtml file to be displayed in the order they are to be displayed in. And so the FIRST item should be the html cover, for example. In each tag, idref= is given the value of the id assigned to the xhtml file in the manifest. Sigil has used the filename as the label (or id) in the manifest but there is as far as I can see no logical reason why some other id could be not used, provided the idref in the spine and the id in the mainfest match. Equally, I can see no good reason to mess with what Sigil has done by default. It works, so don’t fix it!

Out of Sequence (non-linear) items:

There IS a method in the epub specification to separate certain chapters from the main flow of the document. An example might be a textbook in which the author intends including the answers to questions, but does not want the reader to sneakily peek at them, chosing instead to require them to deliberately click on a link. In this case, the answer page would be listed in the spine with an attribute of linear="no". This takes the file out of the normal document flow, and the reader cannot navigate to it using the next/previous page buttons. It will still be there, but the reader won’t be able to see it unless they click on a link. Such xhtml files must still be listed in the spine and there must be some way to navigate to them within the e-book. HOWEVER NOT ALL e-readers are required to support this and an e-reader might simply display all pages, regardless of the vaule of the linear attribute. So I WOULD NOT recommend this strategy, unless strictly necessary. In the example given, I would have thought it was perfectly adequate to put the answers in a chapter at the back of the e-book and link to them as appropriate. The reader would only chance upon them by deliberately navigating to the end. As the pages have to be accessible somehow or other, nothing is really gained by placing them out of the normal flow of the text and it makes the e-book unnecessarily complicated, in my opinion.

If no value of the linear attribute is specified, it is assumed to be "yes" by default, and so for a ‘normal’ e-book in which all the pages fall in a simple linear sequence (recommended), you can ignore this section. For reference, the syntax of a non-linear item in the spine would be:

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

The <guide> in content.opf:

The guide part of content.opf lies between an opening <guide> tag and a closing </guide> tag. It identifies specific parts of the e-book to make it possible for an e-book reader to conveniently access them. Like the ncx, the way an e-book reader’s software would do this would vary from one device to the next.

HOWEVER according to the opf specification e-book readers are NOT required to take any notice whatever of anything which might be in the guide. A specific exception is the html table of contents, which in a kindle MUST be entered in the guide. This is how the kindle software is set up. (See also below for specialised information about the cover in a kindle.)

But, before delving into considerations for kindle, let’s look at e-pub. You CAN enter the locations of various parts of your e-book in the guide and an e-book reader might be able to access this and make it easier for a user to find this information, but there is NO guarrantee that this will work consistently on all e-readers, in fact it probably won’t. However, if you want to risk it, here’s how:

Syntax of <guide> entries:

Each entry in the guide is in the form of a single <reference /> tag. One tag per guide item. There is no closing tag; each tag is closed by the ‘ />’ at the end instead (the space matters). An example is:

<reference type="toc" title="Table of Contents" href="Text/Contents.html" />

Within the <reference /> tag, type specifies the part of the e-book which is being referred to. The value must be chosen from the list below. The title part is not discussed in the opf specification and I assume this can be some informative description of the item to be displayed by the e-reader (although curiously the button on the Kindle which this particular item accesses is NOT capitalised identically with what appears in the title field). And then the href is the location of the item within the e-book. (The examples in the opf specification AND in the Kindle Publishing Guidelines omitted the path. I have added a path in in all my e-books with no ill results.)

The type field can have one of the following values:

type description (if not obvious)
cover the html cover
toc the html table of contents
loi list of illustrations
lot list of tables
text the first page of the main text

The type MUST be entered exactly as it appears in the first column above and is case sensitive. See my post on how to sequence an e-book for a discussion of each of these parts of a book and their conventional location in the text. The type values in the table were taken by the epub consortium from the 13th edition of The Chicago Manual of Style.

IF none of the above is suitable, then you are allowed to define your own type, beginning it with other, then a full-point and then your custom type. An example would be:

<reference type="other.half-title" title="Half Title" href="Text/halfTitle.xhtml" />

HOWEVER e-readers are NOT required by the epub specification to suport ANY guide items, and so, beguiling though the thought of including all the various parts of your e-book in the guide might be, I would suggest it were best to rely instead on your html table of contents to allow your readers to find the various parts of the e-book. The results of including guide items would be variable depending on the particular e-reader in use and it seems to me that you need your e-book to behave the SAME way WHATEVER e-reader your customer happens to have. An exception is the html table of contents which MUST be linked in the guide for a kindle ONLY.

Tables of Contents in a Kindle:

As I have already described, the html table of contents has to be entered in the guide in a Kindle. It should also be listed in the manifest and in the spine in the usual way. This is in addition to the ncx table of contents, which should also be listed in the manifest and, as outlined above, entered in the opening <spine …> tag.

So the complete syntax for the tables of contents in a kindle is as follows:


<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />

<item id="Contents.xhtml" href="Text/Contents.xhtml" media-type="application/xhtml+xml">

<spine toc="ncx">

<itemref="Contents.xhtml" />


<reference type="toc" title="Table of Contents" href="Text/Contents.xhtml" />


The example above uses the labels (ids) given to each item by Sigil by default.

I stress that the above relates ONLY TO KINDLE and if you are at the stage of making an e-pub you should ignore this for now. I cover this topic fully in these posts: how to link and how to restructure the html table of contents for Kindle (in that order). You may also find my posts on how to generate and how to style the html table of contents, how to generate the logical table of contents and how to understand the ncx table of contents useful.

Kindle Cover Image NOT to be referenced in the guide:

The cover in a Kindle should normally be linked rather differently from the way it is linked in an e-pub.

Amazon require an entry making in the <metadata> for the cover IMAGE. This is a proprietary variation from the e-pub specification (although with their blessing) and applies to KINDLE ONLY. I have added a discussion of this here in my post on the metadata, as it properly belongs there. You can also find detailed instructions for deleting the html cover and linking the cover image for kindle (in that order) in earlier posts.

In the context of this post, I would therefore recommend AGAINST including the cover in the guide for a Kindle; the kindle software expects to find the cover image in a different place.

Nothing in the guide:

The logic of the foregoing is that your e-pub e-book will have a completely empty guide section. This is how Sigil makes your e-book by default. In fact, when the guide is empty, Sigil uses a SINGLE self-closed guide tag like this:

<guide />

Note the space between ‘guide’ and ‘/’, which does matter.

If you DO include items in the guide, you should be careful to close it properly. When the guide is NOT empty, it should begin with a an opening  <guide> tag and end with a closing  </guide> tag, which is different from the blank  ‘<guide /> tag. If you get it wrong in your kindle, the html table of contents button will be greyed-out. This is an error which can be particularly difficult to spot: when I made it it took me a whole day before I realised what I had done!!


As a final note, I should mention that it IS possible to provide a ‘tour’ of your e-book (or even more than one ‘tour’), although they are officially frowned on (or in technical language: deprecated). In the context of an e-book, a ‘tour’ is a pre-planned series of locations within the book from which the reader can freely explore the text, much like a set of pre-planned bookmarks. E-book readers are NOT required to support tours (although some might do) and for the same reasons as already given for not including non-linear spine items I DO NOT recommend having a ‘tour’ of your e-book. Sigil is NOT set up to do this and only some e-readers (if any) will implement a tour. They are a hang-over from the original purpose of the specifications adopted into the e-pub standard from those for making audio books. If you want to know how a tour should be implemented, I would refer you to this place in the opf specification (link referenced on 2 Nov 2014). You would have to use an html editor such as Komodo Edit to create a tour, Sigil will not do it for you.


In retrospect, much of this post has been devoted to things you should in my opinion LEAVE OUT of your e-book. I believe an e-book should be as simple as possible, and then there is less that can go wrong. With the important exception of the html table of contents in a Kindle, which is a special case, I would not include any guide items, and would restrict the spine to linear items. The ncx has to be linked in the spine as shown above, but that’s about it. Keep it simple! The html table of contents will provide a perfectly straightforward way for the reader to locate items within your e-book. And listing the cover as the first item in the spine will ensure it is the first thing in the [e-pub] e-book. It is, however, important that the content in your e-book follows the conventional sequence for a print book, as the reader will be familiar with this. See my post on how to sequence an e-book for more information.

Next Steps: Now, finally, you should have a complete e-pub e-book and you are ready to test it using the tools (flightCrew) built into Sigil and also with epubcheck. My next posts will cover how to do this. You can then begin converting it to Kindle.

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
How to adapt the print index in your MS Word file for an e-book using markup
How to adapt cross-references in your print index for e-book and how to use markup to make the links
How to understand content.opf
How to understand and edit the Metadata of an ebook using Sigil
How to understand the manifest in content.opf
How to understand the spine and guide in content.opf
How to test your e-pub using flightCrew in Sigil
How to test your e-pub using epubcheck
How to convert an e-pub to Kindle using kindlegen

TinyURL for this post:

No comments:

Post a Comment

Twitter Bird Gadget