Where do you start an ePUB and what is the <guide> section of the .OPF file?

  • Sumo

Liz Castro has a great post at her blog Pigs, Gourds, and Wikis titled “Where should an ebook begin?” In the post, she looks are various readers and what they usually show as the first page of an eBook of John Grisham’s The Litigator. As she shows, both the Kindle and iBooks open to the first page of the first chapter of the book. The Nook, however, opens to the first page of the eBook itself, that is the cover, because it currently does not recognize the reference type "start" in the <guide> section of the .OPF file. In my own testing, it appears that Adobe Digital Editions (ADE) doesn’t support "start" either.

The <guide> section is in some ways the red-headed stepchild of the .OPF file. It is generally the last content in the .OPF, and isn’t as familiar to most ePUB producers as the other parts. To understand it, let’s take a quick look at what makes up the .OPF file.

The .OPF file begins with a declaration and package tag that looks something like this:
<?xml version="1.0" encoding="UTF-8"?>
<package version="2.0" unique-identifier="PrimaryID" xmlns="http://www.idpf.org/2007/opf">

This is followed by the <metadata> section, which has Dublin Core defined fields of information about the ePUB, plus the <meta name="price" content="USD XX.XX"/> and <meta name="cover" content="my_cover_image"/> tags.

Next is the <manifest>. This a list of each item that is considered part of the publication: a document, an image file, a style sheet, or other component. Each item is defined with the following attributes: id, href, and media-type.

After the <manifest> is the <spine>. The <spine> defines the reading order of all media-type="application/xhtml+xml" or "application/x-dtbook+xml" files. Each itemref includes an idref that matches the id given to the file in the manifest and a linear= attribute, which determines whether the file will show up as the reader turns pages or if the file will only be accessed through a link. A typical item entry would look like this: <itemref idref="toc" linear="yes"/>

Finally, we get to the <guide>. According to the official IDPF specs for ePUB, “The guide element identifies fundamental structural components of the publication, to enable Reading Systems to provide convenient access to them.” So how does the <guide> work? Essentially, it points to where particular pieces of the book can be found, allowing reading systems to go directly to that file or location.

The structural components of the books are listed in reference elements contained within the <guide> element. These components could refer to the table of contents, list of illustrations, foreword, bibliography, and many other standard parts of the book. Reading Systems are not required to use the <guide> element in any way.

The structural components of the book that can be included in the reference type are:

  • cover   the book cover(s), jacket information, etc.
  • title-page   page with possibly title, author, publisher, and other metadata
  • toc   table of contents
  • index
  • back-of-book
  • style
  • index
  • glossary
  • acknowledgements
  • bibliography
  • colophon
  • copyright-page
  • dedication
  • epigraph
  • foreword
  • loi   list of illustrations
  • lot   list of tables
  • notes
  • preface
  • text   First “real” page of content (e.g. “Chapter 1”)

Other types may be used when none of the predefined types are applicable; their names must begin with the string other. The value for the type attribute is case-sensitive.

You’ll note here that the actual ePUB 2 spec calls for text to be used instead of start, as recommended by Amazon for Kindle. After some testing by Liz Castro, I can report that both will actually work on the Kindle and in iBooks. If you want to follow the ePUB spec properly, you may want to choose text in your <guide> section.

So why use <guide> items? One reason is that if you are running your ePUB through KindleGen or are using your ePUB HTML files for Kindlegen, including reference type="cover", reference type="toc", and reference type="start" will create links for these items in your Kindle edition. As the Amazon Kindle Publishing Guidelines state:

The Kindle platform supports guide items for defining the cover, the table of contents (TOC), and the start reading location (“Go To Beginning”).
We do not recommend adding additional guide items to your OPF file beyond these, as they will be grayed out in the menu options and may cause customer confusion. Important: Please note that guide items, especially the TOC guide item, are not intended to replace the table of contents.

iBooks also supports both start and text. If you want the reader to go directly to the first page on content in your book and bypass the frontmatter, it makes sense to include it in ePUBs uploaded to iBooks.

I have usually included only the three <guide> elements recommended by Amazon since it doesn’t appear that anything besides these three items is accessed by any reading platform. In the OPF file, it looks like this:

image of the &lt;guide&gt; section of an OPF file

The <guide> section of an OPF file.

In the ePUB 3.0 spec, <guide> is deprecated. This means that it isn’t necessarily recommended for use, but it will still work. The ePUB 3.0 spec recommends using landmarks as part of the new nav page, and landmarks include pretty much everything in the guide and more.

Are you using the <guide> section as part of the OPF in your ePUBs? Have you found any additional function for it on any of the reading platforms?

9 Responses to “Where do you start an ePUB and what is the <guide> section of the .OPF file?”

  1. David B says:

    Wow! I love having this kind of depth reporting! Definitely the kind of thing that needs to be bookmarked.

  2. Doug says:

    It shouldn’t be surprising that NOOK and Adobe Digital Editions behave the same, since NOOK uses Adobe Reader Mobile software for processing EPUBs.

  3. Gudrun says:

    I believe that Apple is also using the reference “start” to mark the start to auto generate the preview file.

  4. India says:

    Although iBooks doesn’t seem to actually use it at present, Apple’s upload validator requires fixed-layout books to include a starting location of the type “text” or “bodymatter” in the guide. Perhaps they’re planning to hook some functionality to that location in a future release.

  5. Une calmasse faudrait s’diriger d’la aplatisse flagrants prétextes payants

  6. Genoskill says:

    Nice and informative post. Thank you sir.

  7. 財布コピー、バッグコピー、腕時計コピー、ベルトコピー靴コピーネックレスコピー、手帳コピー、小物コピー、SS品、N品、価格激安、品質の保証,2015人気ブランド偽物,歓迎光臨楽天★送料無料(日本全国)典雅気質!シャネルバッグCHH67723(*^^*)11月シャネル手作り新作(*^^*)時流の先端快適美品!シャネルブーツCH783283四季向け「 シャネル靴」最高な選択!ブランドコピー 代引きコピーブランド 代引きスーパーコピー 代引きスーパーコピーブランドバッグルイヴィトン コピーシャネル コピー
    スーパーコピー時計専売店当店は海外安心と信頼のスーパーコピーブライトリング、代引き店です.正規品と同等品質のシャネル コピー代引き,品質が秀逸,値段が激安!ブライトリングコピー,代引きなどの商品や情報が満載!全商品写真は100%実物撮影です! お客様の満足度は業界No.1です!スーパーコピー時計,時計コピー ,ブランド時計コピー販売(n級品)店舗 ブランド腕時計(ロレックス,ブライトリング,タグホイヤー,オメガ,ガガミラノなど)の最新 情報やイベントを紹介する正規販売店と腕時計コピーの専門サイトです。当店はロレックスやパテックフィリップなどの新品スーパーコピー時計の販売と。 http://www.wtobrand.com/lv1.html

  8. 春夏シーズンでも好評だった、
    2015年の新素材-新作!高品質 腕時計高品質の追求 超N品を良心価格で提供詳しくは以下のようなブランドがあります。HERMES(バッグ、財布、時計) CHANEL(バッグ、財布、時計)LOUIS VUITTON(バッグ、小物、財布、時計) BVLGARI(財布、時計)Christian Dior(バッグ、財布) COACH(バッグ、財布)GUCCI(バッグ、財布) ROLEX(時計)OMEGA(時計) IWC(時計)FRANCK MULLER(時計) HUBLOT(時計)クロエ CHLOE バッグなどです。ご不明点が ございましたらお気軽にお問い合わせください http://www.gginza.com/wallet/louisvuitton/index_5.html

  9. 期待,
    BVLGARI(バッグ?財布?小物)CHLOE(バッグ?財布、小物)偽物ブランド,激安,コピー?ルイヴィトンバッグ,偽物?ルイヴィトン財布,コピーバッグ,ブランドバッグ,偽物バッグ,偽物シャネルバッグ,偽物エルメスバッグ,偽物グッチバッグ,偽物財布,コピー財布,時計の專門店 http://www.gowatchs.com/brand-258.html