Friday, January 20, 2012

Manifest, Spine, and Tours

I decided to combine what I've learned about the manifest, spine, and tours sections of a mobipocket book's .opf document into one post. The first two are linked in that the "item id" in the manifest must match exactly the "itemref idref" in the spine. There’s not much to say about tours, but what I know, I share below.

First, I want to show you how River's Bend's final manifest, spine and tours sections turned out:

<manifest>
<item id="toc" media-type="application/x-dtbncx+xml" href="toc.ncx"></item>
<item id="item1" media-type="text/x-oeb1-document" href="Riversbend.html"></item>
<item id="item2" media-type="image/jpg" href="Riversbendcover.jpg" ></item>
<item id="item3" media-type="image/jpg" href="Riversbendlogo.jpg"></item>
</manifest>

<spine toc="toc">
<itemref idref="item1"/>
<itemref idref="item2"/>
<itemref idref="item3"/>
</spine>

<tours></tours>

The manifest lists the files that make up the mobipocket book, and the spine arranges the documents in a linear reading order. The manifest begins with a <manifest> element and contains an "itemid" for each "item" making up the book. Each item is annotated by its "media type," a declaration of what kind of item it is. Choices include "text" (the .html book), "image" (cover and/or logo and any other pictures in the book), "application," I assume that means how it's applied or used within the book (i.e. the navigational table of contents--.ncx file), and "font." That would be an embedded font, and I’m pretty certain embedded fonts are not applicable to a mobi book.

The section closes with the corresponding </manifest> tag. In the case of River's Bend, the manifest includes the toc.ncx file; the novel formatted in .html; and two graphics, one being the cover and the second, Loblolly Writer's House's logo, which appears on the book's title page. Four items, that's all.

The Spine section, as you’d expect, opens with a <spine> tag and closes with </spine>. In between, it tells the e-Reader (the machine not the person) the order in which to read the files. You can see the relationship between the item id in the manifest and the itemref idref noted in the opening paragraph of this post. Except for...

Okay, I admit it, the spine has caused me some confusion. In River's Bend's file, I called it, not "<spine>," but "<spine toc="toc">." My guidance came from Joshua Tallent in his example of the .opf file in Chapter 7 of Kindle Formatting (see sidebar).

Now, look at the manifest. The first item id in the manifest="toc" and its href is the "toc.ncx" file. Yes, that's right; it should be the toc.ncx element, but why isn't there a spine itemref idref like this

<spine>
<itemref idref="toc"/>

to make the spine parallel with the manifest?

First off, Elizabeth Castro states in Chapter 3 of EPUB Straight to the Point (see sidebar) that the spine element "must have a toc attribute whose value matches the value of the id in the item that referenced the toc.ncx file in the manifest." Now, I've noticed that what's right for epub more often than not is right for mobi. The two are kissing cousins, so that explains that. And although the "toc" attribute in the spine header is present (<spine="toc">) in Joshua Tallent's example, the itemref idref="toc" in the spine's body is not. His spine is very simple:

<spinetoc="toc">
<itemref idref="item1"/>
</spine>

"Item 1" in his example references the .html book itself, the reference to the table of contents being covered in the spine's opening tag.

Now, let's keep going. In April L. Hamilton's example of the spine in her Indie Author Guide To Publishing for The Kindle (see sidebar), there is an itemref idref="toc" in the body of the spine, but if you look at Liz Castro's example of the spine in Chapter 3 of EPUB Straight..., she does not place the itemref idref="toc" [or maybe it should read "ncx" ?] within the spine either.

I conclude that the digital book works either way. Which way is the correct way is a different matter. Certainly mine, without the itemref idref="toc" within the spine, works fine, and I'd be willing to bet everything April Hamilton formats works, too. By my own assessment (I've already told y'all I can be anal), I think the itemref idref="toc" should be in the body of the spine section. If so, River's Bend's spine should actually look like this:

<spine toc="toc">
<itemref idref="toc">
<itemref idref="item1"/>
<itemref idref="item2"/>
<itemref idref="item3"/>
</spine>

Anal or not, I'm not about to tempt fate. My River's Bend Kindle book works as is, and I "ain't" messin' with it. I will change the template, though, and see how Epico Bayou works with the itemref idref="toc" within the spine.

<tours></tours>

Here's how the International Digital Publishing Forum defines the <tours></tours> element: "A set of alternate reading sequences through the publication, such as selective views for various reading purposes, reader expertise levels, etc."

Got that? Neither did I.

River's Bend's "tours" section is empty. In truth, the tours section is deprecated. I do wonder what would happen if I deleted it from my .opf document altogether. I'd be willing to bet if my itemref idref="toc" missing from the body of my spine slips by unnoticed, the same would be true of a non-existing tours, but then I think if I ever understand its purpose, I might use it someday. It can be used and probably is by somebody somewhere. I’m just gonna leave it. Everyone else does.

Want to study more? My resources are in the sidebar.

Thanks for reading. Next week I plan to finish up the .opf file with the "guide" section.

Charlsie

5 comments:

  1. For what it's worth, the example provided by Amazon for Kindle is this:

    <manifest>

    <item id="document" media-type="text/x-oeb1-document" href="telehealth_2u.html"></item>

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

    <item id="My_Cover" media-type="image/gif" href="telehealth_2u_cover.tif"/>

    </manifest>

    <spine toc="toc">

    <itemref idref="document"/>

    </spine>

    <tours></tours>

    <guide>

    <reference type="toc" title="Table of Contents" href="telehealth_2u.html#TOC"></reference>

    <reference type="start" title="Startup Page" href="tele_law_ethics.html#start"></reference>

    </guide>

    ReplyDelete
  2. But I should add, toc references the ncx file:

    Per the annotated sample: "The toc attribute refers to the id ref of the NCX file specified in the manifest."

    ReplyDelete
    Replies
    1. Bob, my apologies for not responding to your interest sooner. I've been out of the country--and thought I'd be notified of any comments. I had my computer...but missed the comments to my blog completely. I do appreciate your visit and helpful entries.

      I don't think I ever saw Amazon's examples while I was working on this. I used Joshua Tallent, Liz Castro, and April Hamilton and pieced it all together by trial and error, WAGs and luck. I've also now printed out what you sent me. I'm hoping to plug in my remaining books to the templates I created for River's Bend and they'll all work flawlessly. I am laughing at that comment!

      Thanks for your visit and again I apologize for the delay in my response.

      Charlsie

      Delete
  3. Once again excellent publish. You seem to have a excellent knowing of these styles.When I coming into your site,I sensed this . Come on and keep blogging your site will be more eye-catching. To Your Success!

    ReplyDelete

I encourage you to leave comments. I'll reply to all questions within a week, and errors in the posts will be acknowledged in the comment area. Feel free to answer questions/clarify confusion I express in my posts. Disagree with my points if you believe there is need for disagreement, but keep in mind that all off-topic comments, disparaging comments, comments with more than one link, and comments that include profanity will be deleted.