Example - The Well-Grounded Rubyist

This page provides specific information regarding the EPUB variant used in "The Well-Grounded Rubyist".


The EPUB variant used by this book largely matches that described in EPUB 3 Best Practices, but there are some exceptions.

Because this is an EPUB 2.0 document:

  • There is no NAV file (defined in EPUB 3).

  • There is an NCX file (defined in EPUB 3).

The NCX file (toc.ncx) covers the Part, Chapter, and Section levels.


Manning produces a large number of high-quality technical reference works for software developers. Let's examine their EPUB archive for The Well-Grounded Rubyist.

File Tree

The file tree contains about 200 hundred files, all of which (except for META-INF/container.xml) reside in the top-level directory (tsk).

| *fig*.jpg              # images for figures
| arrow.jpg              # small, right-pointing arrow
| black_circle_*.jpg     # white number in black circle
| circle_*.jpg           # white number in black circle
| content.opf            # Open Packaging Format (XML)
| cover.jpg              # image for cover page
| infi.jpg               # encircled infinity symbol
| iTunesMetadata.plist   # iTunes property list (XML)
| kindle_split_???.html  # content, split for Kindle
| logo.jpg               # image of Manning logotype
| m.jpg                  # image of Manning "M" logo
| META-INF/              # EPUB metadata
| | container.xml        # media type, paths (XML)
| mimetype               # "application/epub+zip"
| stylesheet.css         # CSS for calibre, etc.
| titlepage.xhtml        # CSS for title page
| toc.ncx                # table of contents (XML)

Package Document

Per META-INF/container.xml, content.opf is our package document. This is a substantial file (273 lines), so here's another summary:

package       # unique-identifier, version, xmlns
| metadata    # xmlns:dc, xmlns:opf
| | dc:*      # creator, identifier, language, ...
| manifest    # list of files included in document
| | item      # id, href, media-type
| | ...
| spine       # toc="ncx"
| | itemref   # idref=titlepage
| | itemref   # idref=html57
| | ...
| | itemref   # idref=html1
| guide
| | reference # href, title, type


The spine entry lists the enclosed content files, in the "normal" reading order. The toc attribute's value (ncx) tells us to look for toc.ncx, a file which contains EPUB 2 navigation hints and other metadata.


The guide entry lists only one reference:

  • The cover page ("Cover") is "titlepage.html".

NCX file

The NCX Navigation Center eXtended file (toc.ncx) is included for backward compatibility with EPUB 2. Although navPoint entries can be nested to indicate hierarchy, Careful Reader will note that "Part 1: Facets of Ruby" is just a divider page. So, a key part of the book's tree structure has been discarded; to restore this, AxAp will need to rely on naming hints (e.g., "Part 1"):

Brief Table of Contents
Table of Contents
About this Book
About the Cover Illustration
Part 1. Ruby foundations
| Chapter 1. Bootstrapping your Ruby literacy
| ...

This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r7 - 27 Oct 2016, RichMorin
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email