Inside epub

2010-02-18T17:40:00.005Z

The purpose of this post is to review progress on the project to develop an online wysiwyg epub editor. For a number of reasons it's a good time to pause and reflect on what's been achieved and to identify what remains to be done.

I've built up a basic library of epub classes to handle the functionality of epub editing - classes to handle the container, the package with its metadata, manifest, and spine, and the NCX.

At the front end, the user can perform the following:

Create a new epublication (a term I prefer to 'epub publication').
Insert a basic set of metadata items for the new publication.
Limited editing of metadata for an existing publication.
Create and manipulate content documents.
Add images to the manifest and insert them (sort of) in a content document.
Edit the CSS files of the publication.

The screenshots shown below illustrate this functionality.

However, there are aspects of an online system that can no longer be ignored. For instance, the application needs to be multi-user. To date I've worked with a single server folder for the epub library whereas each user needs a folder to hold their own library and to act as a work area for writing. The need to handle many users immediately suggests some kind of database would be useful; so far I've held data in constants, in the web.config and, embarrassingly, as hard-code. It's time to organise this better.

This review will step through the existing functionality and will identify where and how the application should be enhanced.

Library (Books View)
The screenshot in figure 1. shows the opening page of the application. It presents a list of books and a button for creating a new epub.

Figure 1. Books View

The user clicks on the book they want to open or clicks on the 'New epub' button to start a new publication. Currently, the list of books is fetched by extracting a folder path from web.config. All files with the extension .epub are shown in the list.

Design Improvements
The following enhancements are deemed to be either essential or desirable:

The application should be multi-user. User registration and login should be handled by the Membership Service using the range of built-in Login controls. This should use a SQL-Express database in the App_Data folder.
Additional user information should be held; in particular a folder on the web server should be assigned for each user's work. This root folder would be the place to hold the user's library and it is from this folder that the Books list would be populated.
It would be friendlier to display the title of the book rather than the filename for each book, for instance 'The Curious Case of Benjamin Button' rather than 'fitzgerald-curious-case-of-benjamin-button.epub'.

Metadata (Book Information View)
In figure 2. the Book Information view is shown. This displays the <metadata> from the publication's package document.

Figure 2. Book Information View

The user can modify any items on the screen and click the Save button to store the changes in the epub.

A review of the Open Packaging Format Schema shows, however, that the handling of metadata needs to be more sophisticated. Figure 3. is an extract from the schema showing the definition of metadata-content.

<define name="OPF20.metadata-content">
<choice>
<interleave>
   <ref name="OPF20.dc-metadata-element"/>
    <optional>
     <ref name="OPF20.x-metadata-element"/>
    </optional>
</interleave>
<interleave>
   <oneOrMore>
    <ref name="DC.title-element"/>
   </oneOrMore>
   <oneOrMore>
    <ref name="DC.language-element"/>
   </oneOrMore>
   <oneOrMore>
    <ref name="DC.identifier-element"/>
   </oneOrMore>
   <zeroOrMore>
    <ref name="DC.optional-metadata-element"/>
   </zeroOrMore>
   <zeroOrMore>
    <ref name="OPF20.meta-element"/>
   </zeroOrMore>
   <zeroOrMore>
    <ref name="OPF20.any-other-element"/>
   </zeroOrMore>
</interleave>
</choice>
</define>

Figure 3.OPF20.metadata-content

The <oneOrMore> wrapped around the title, language, and id elements indicates that there must be at least one of these elements in the metadata, but there may be more. The <zeroOrMore> identifies elements that are optional. However, the OrMore part of the definition means there can be many of these elements too. We've already seen in earlier posts that there can be a range of dates, creators, contributors, and descriptions. In fact the schema says there can be any number of these items.

Design Improvements
The following enhancements are essential for handling the metadata of an epublication.

Handle multiple instances of any metadata element.
It should be possible to add, modify, and delete metadata elements.
All metadata elements can be deleted except for one each of title, language, and id.

Book Content
Figure 4. shows the latest incarnation of the Book Content view.

Figure 4. Book Content View

The functionality of this screen has been changed since it was last presented. The most significant differences are:

Drag and drop functionality to move content documents within the publication. This activity is enabled/disabled by the 'Organise' checkbox. The Move Up/Move Down options were removed from the Action dropdown as they are no longer needed.
The tinyMCE editor, which is where the content documents are displayed, has been configured with a default font size that's easier to read and a drag handle has been provided to allow the user to change the height of the text area.
The new document details - Contents Entry and Document Heading - were moved above the editing area to allow the resize facility just mentioned.
The ability to put a heading at the top of a new content document was made optional.
Not shown in the screenshot, a 'boiler-plate' copyright document is inserted after the title page when a new epublication is created. It uses text like the following, where names and dates are taken from the metadata and inserted into the text at fixed locations. An author or publisher could change the text to that of their choice.

Copyright © Colin Hazlehurst, 2010

Colin Hazlehurst asserts the moral right to be identified as the author of this work.

No part of this publication may be reproduced, stored or introduced into a retrieval system, or transmitted, in any form or by any means, without the prior written permission of both the copyright owner and the publisher of this work.

Design Improvements
There are still useful enhancements that could be made to this view:

The ability to promote and demote content document and reflect the changes in the <navMap> of the NCX document.
The code should start with the Save button disabled. It should detect when either the Table of Contents or the text of the currently displayed content document are changed. It should then enable the Save button. The Save button should be disabled after any changes have been saved.
There is a particular challenge with respect to handling images which is the subject of a separate note below. The problem is that the href of an image in the manifest is relative to the document which references it. When displaying the image in a browser, the URL in the image's src attribute needs to specify a path on the server relative to the root of the application.

Media View
Figure 5. shows the view when the user clicks on the Media tab. The application reads the manifest and finds all files that have a media-type beginning with the text 'image/'. For each file it finds, an Image control is added to the view and the source is set to the href for the manifest item.

Figure 5. Media View

A FileUpload control works in conjunction with an Upload button to allow the user to upload a new image for inclusion in the publication.

Design Improvements
The following enhancements would greatly improve the handling of media by the application.

Media types other than images should be handled.
Some ability to generate thumbnails should be included which would keep the correct aspect ratio for each image.
Currently images cannot be selected for deletion.

Styles View
Remembering that the value of XHTML is that it gives structure to the content of a document, but it also separates the content from its presentation. The widespread tool-of-choice for presenting content is CSS. epublications can incorporate any number of CSS stylesheets to help present the content.

Figure 6. shows the Styles tab in the epub editor project.

Figure 6. Styles View

When the user clicks on the Styles tab, the application reads the manifest and finds all files that have the media-type 'text/css'. It constructs a list of these files and allows the user to select one by clicking on it. In the example shown, main.css was selected and the stylesheet is displayed.

The 'Action' dropdown list gives the user the ability to add and remove CSS files. The Save button is used to save any changes the user makes to the currently displayed stylesheet.

Image Handling Issue
It was mentioned above that there is an issue with the handling of images that is particular to the online environment. The href of an image in the manifest of an epub is set relative to the content document that references it. On the web, the src attribute of the image control is a URL relative to the root of the web application.

In the Benjamin Button example, the ePubBooks logo is referenced on the epubbooksinfo page in the OPS folder. The href is set to 'images/epubbooks-logo.png', and the logo is held in folder OPS/images. A web page with a root folder called epub displaying the epubbooksinfo page in a tinyMCE editor would expect to find the logo in folder .../epub/images.

In a multi-user system it would not be possible to put the images for all users' publications in one folder. Each user must have their own work area, which means they must have a separate folder on the server. If F.Scott Fitzgerald were using this application (and who, given the weirdness of Benjamin Button, can say that he can't?), then he might be saving his content in a folder like:

epub/fsfitzgerald/benjaminbutton/OPS

Therefore, to view the image in the browser, its src would need to be something like:

epub/fsfitzgerald/benjaminbutton/OPS/images/myimage.svg

The epub must reference the image simply as: images/myimage.svg.

This difference in addressing must be handled by the application. The obvious choice is to use a pair of XSL transforms, one of which builds a web-relative URL and replaces the src attributes of all images in a content document with this value. This transform runs when the user selects a document from the table of contents to display it in the editing area.

The other transform runs when the user clicks the Save button after making changes to a content document. It strips out the web path and replaces it with a document relative path. The content documents saved to the filesystem and thus in the .epub must always use the document relative path - that's the only way the epub can be shipped.

How do you get to Carnegie Hall?
So that's the job facing me on this project. It's interesting, but time consuming. To sum up the way I feel is like:

Tourist: How do you get to Carnegie Hall?
Yokel: Well, you wouldn't want to start from here.

Manifest and spine management in C#

2010-02-16T15:47:00.006Z

This post presents the requirements for C# classes that manage the manifest and the spine - both of which are elements in an epub package. The manifest identifies all of the files that are part of a publication while the spine specifies the linear reading order of its content documents.

A reading system needs only to read and parse these elements; it doesn't modify them in any way, with one exception. However, an online wysiwyg epub editor needs the ability to insert, remove, and rearrange files in both the manifest and the spine.

Manifest Items
The <manifest> element of an epub <package> contains <item> elements, one item for each file that is referenced from anywhere in the publication. A manifest item has the attributes shown in Table 1.

Attribute Name	Attribute Description
id	Mandatory, unique identifier of the file within the manifest.
href	Mandatory, URI of the file for this item.
media-type	Mandatory, MIME media-type for this item.
fallback	id of the manifest item to which a reading system should fall back if it is unable to process the namespace of the current item. Mandatory when the current document is an Out-Of-Line XML Island.
fallback-style	id of the manifest item which holds a CSS stylesheet using which the contents of the current item may be rendered.
required-namespace	When the current document is an Out-Of-Line XML Island, this attribute must be present and it should be set to the namespace of the document.
required-modules	A comma-separated list of Extended Modules, which might belong to XHTML or to the namespace of an Out-Of-Line XML Island. This list of modules helps the reading system decide whether it has the capabilities to process the current item.

Table 1. manifest item attributes

In the context of a C# class designed to read and write manifest items, these attributes are simply strings to be accessed through the methods and properties of the class.

Attribute Handling Methods
Extracting the attributes of an XML node is a common activity in epub code. The most succinct code to access an attribute value is:

XmlNode targetAttribute = node.Attributes.GetNamedItem(attributeName);

However, many attributes are optional, and the variable targetAttribute will be set to null if the attribute is not present. Therefore, I prefer to wrap this statement up with some defensive programming which checks for a missing attribute and also distinguishes the case where the attribute is present but is set to an empty string. I use an overloaded TryGetAttribute method which offers a few ways of handling these situations. One example of the method is shown below.

public static bool TryGetAttribute(XmlNode node
   ,string attributeName
   ,out string attributeValue) {

// initialise the results
bool result = false;
attributeValue = string.Empty;

// try to get the named attribute
XmlNode targetAttribute = node.Attributes.GetNamedItem(attributeName);

// if the attribute was found
if (targetAttribute != null) {
// extract the value and set the result to true
attributeValue = targetAttribute.InnerText;
    result = true;
}
return result;
}//TryGetAttribute

The converse of reading a potentially missing attribute occurs when we want to set the value of an attribute that may or may not be present in the target XmlNode. Again, this happens often enough to make it worth creating a method to handle it. I call this SetOrAddAttribute and a listing is shown below.

public static void SetOrAddAttribute(XmlNode node,
   string attributeName, string attributeValue){
// try to get the attribute
XmlAttribute targetAttribute = TryGetAttribute(node, attributeName);
// if the attribute is not present in the given node
if (targetAttribute == null){
    // create and add an empty attribute
    targetAttribute = node.OwnerDocument.CreateAttribute(attributeName);
    node.Attributes.Append(targetAttribute);
}
// set the attribute value
targetAttribute.InnerText = attributeValue;
}

The manifestitem class
With attribute handling in place, it's straightforward to create a manifestitem class in C#. The constructor is given a reference to an XmlNode which it stores in a private variable:

private XmlNode _node;

public manifestitem(XmlNode node){
_node = node;
}

Each attribute of the manifest item is then provided with a property which can be used to get and set the attribute value. For example, look at the following snippet which handles the href attribute

public string href {
get {
string _href;
utilities.TryGetAttribute(_node,"href", out _href);
return _href;
}
set {
utilities.SetOrAddAttribute(_node, "href", value);
}
}

The get method returns the attribute value, if it is present, or an empty string. The set method replaces the value of any existing href attribute or adds an href attribute with the given value if the attribute is not present in the item node.

This pattern is repeated for each attribute.

The manifest class
A C# class to handle an epub's manifest is concerned with the manifest's <item> elements. It needs to find them, add them, and remove them. To that end the methods in Table 2. make up the manifest class which is part of the project to develop an online wysiwyg epub editor.

Method	Description
manifest(XmlDocument package)	Constructor which receives the epub package as an XmlDocument.
ManifestNode()	A method which returns the <manifest> as an XmlNode.
ManifestItems()	Method returning the manifest item elements as an XmlNodeList.
Add(manifestitem item)	Method to add the given instance of a manifestitem to the manifest.
Add(string id, string href, string media_type)	Method to add an item to the manifest, assigning it the given mandatory values for id, href, and media-type.
Remove(string id, string packagePath)	Remove the item with the given id from the manifest. Also, delete the file from the file system using the physical path in the packagePath argument.
GetManifestItemById(string id)	Return the item element with the given id as a manifestitem instance.
CreateManifestItem()	Create a new manifestitem instance which can be adorned with attribute values and inserted in the manifest using the Add method.

Table 2. properties and methods of the manifest class

Note that the node order in the manifest is not important, unlike in the spine. Therefore, the Add methods simply append new items at the end of the manifest.

Spine
In some ways the <spine> is easier to handle than the <manifest>; there are fewer attributes to work with; but it does have a few complications. Firstly, the <spine> element includes the toc attribute which holds the id of the manifest item that holds the NCX document for the publication. That attribute has to be accessible so the reading software can find and open the NCX.

Secondly, the spine provides the reading system with the linear reading order of the content documents. Therefore, the order of the nodes in the spine is important.

Spine nodes are called <itemref> because they refer to items in the manifest; the idref attribute of each itemref element is the id of a manifest <item>. Each item id must only appear once in the spine.

The only other attribute that the Open Packaging Format schema allows is the linear attribute. This distinguishes primary content documents (value="yes") from auxiliary content documents (value="no"). "yes" is the default, so this attribute can be omitted.

Useful Enumerations
Before presenting the spine class, it's worth introducing two enumerations that support the code. The first of these describes the position where a new spine itemref should be inserted. The InsertPosition enumeration is shown below.

public enum InsertPosition {
   after
   ,before
   ,bottom
   ,top
}

This provides options to insert a new itemref at the top or bottom of the reading order, or to insert it before or after a given other itemref node.

The second enumeration allows the code to specify the value of the linear attribute without passing a string. The Linear enumeration is show below.

public enum Linear {
yes
,no
}

The spine class
A C# class to provide basic handling for the <spine> element could have the methods and properties shown in Table 3.

Method	Description
spine(XmlDocument package)	Constructor which receives the epub package as an XmlDocument.
tocId	Return the id of the NCX manifest item from the toc attribute of the spine element.
itemrefs	Method returning the itemref elements as an XmlNodeList.
Add(string idref, InsertPosition ip, string refNodeId, Linear linear)	Add an itemref instance to the spine. The new itemref will have the given idref and linear values, and the position will be determined by the InsertPosition value relative to the itemref element which has the idref value in the refNodeId argument.
Remove(string id)	Remove the itemref with the given id from the spine.

Table 3. properties and methods of the spine class

Earlier I mentioned that with one exception a reading system does not modify the manifest or the spine. The Open Package Format says that any part of the publication that can be referenced during processing of an epub must be included in the spine. However, if the reading system encounters content that is not present in the spine:

the Reading System should add it to the spine (the placement at the discretion of the Reading System) and assign a value of 'no' to the linear attribute.

So, a reading system can add itemrefs to the spine. I interpret this to mean that the in-memory representation of the spine is modified and not the package file in the file system nor the compressed version of the package held in the .epub file. Please contradict me if you know this to be false.

XML Islands in epub publications

2010-02-15T14:38:00.004Z

Preferred Vocabulary
An earlier post - How the standards work together - showed that the Open Publication Structure (OPS) specifies the XHTML tags, grouped into modules, that should be used to create an epub publication. These modules constitute what is called a Preferred Vocabulary. In other words, the OPS specifies the tags that should be used to define the structure of a work - a <div> here, a <table> there, and so on.

All conforming reading systems must recognise and be able to render documents written using the preferred vocabulary. The term 'baseline' reading system indicates this minimal ability.

Beyond the Preferred Vocabulary
You can achieve a great deal using only the preferred vocabulary. A very high proportion of existing printed matter, including its illustrations, could be transferred to epub format using only the standard OPS modules - with layout and formatting support from CSS. However, that adjective 'preferred' hints that epub productions do not have to be written exclusively in that vocabulary. OPS recognises that there are other tags in XHTML 1.1 that an author might want to use and that there are other XML vocabularies that a publisher might need to include.

XML is a widely used technology. If you enter into Google the search term: 'XML vocabulary for', and follow this with any topic in which you have an interest, there's a good chance someone has designed, or is actively designing, an XML vocabulary for that topic. I found the following; you will find many more:

ceXML - civil engineering XML.
genXML - for the exchange of genealogical data.
mathML - XML for sharing mathematical expressions.
MusicXML - XML for capturing musical notation.

The users of these diverse vocabularies are very likely to want to include content written using them in their epub publications. It might be a fragment of non-preferred XML embedded, as an example, within an otherwise conforming XHTML content document, or it might be an entire document conveying the essential content of the publication.

The Open Publication Structure offers an approach that allows non-preferred content to be included in a publication while ensuring that the content is available, in some form, to all consumers. The trick is to allow reading systems that have been designed to handle the non-standard content to exploit it to the full while insisting that the publisher provide the information in a form that is accessible to baseline readers.

XML Islands
If I were to embed snippets of foreign languages into this post by suggesting per se that it is de riguer to introduce de novo some concept of the deus ex machina, you would rightly accuse me of poor writing style. However, those French and Latin phrases are examples of content taken from another language, or non-preferred vocabulary, emebedded in a stream of preferred vocabulary; in this case it's embedded in English but it could be Greek embedded in Spanish or Mandarin embedded in Tagalog.

It is poor writing style to sprinkle foreign phrases about like this because the reader whose preferred vocabulary is English will not necessarily understand Latin. Likewise, a chunk of XML written using a non-preferred vocabulary will make no sense to a baseline reading system because it is not required to process such content. I'm not saying it's a bad idea to insert 'foreign' XML into a content document, simply that special handling is required when it is used.

Chunks of XML, written in a foreign language and embedded in a stream of preferred vocabulary, are called Inline XML Islands. Islands in the stream, that is what they are.

It is possible for entire content documents to be written in a non-preferred vocabulary. In this case, and because they are not embedded in a stream of preferred vocabulary, these documents are called Out-Of-Line XML Islands, though they are more like continents than islands - entirely inaccessible and incomprehensible to a baseline reading system.

The Open Publication Structure and Open Packaging Format standards define between them what XML Islands are and then state the requirements to be met by publishers when creating them and the guidelines to be followed by reading systems when encountering them in a publication.

Publisher's Responsibilities: Out-Of-Line XML Islands
If a publisher wants to include Out-Of-Line XML Islands in a work, they must meet the following requirements.

The XML Island must be a complete XML document that conforms to its own schema (the schema defines the vocabulary).
The manifest item for an Out-Of-Line XML Island must identify the namespace of the document using the required- namespace attribute.
For each Out-Of-Line XML Island, the publisher must provide a fallback document which can be processed directly. The manifest must include fallback documents as well as the XML Islands they support.
The manifest item for the XML Island must include a fallback attribute, and that attribute should give the id of the fallback document.
If necessary, a fallback item may itself have a specified fallback, creating a fallback chain.
Fallback chains must not form a loop.
As an alternative to a fallback item, the publisher may provide a stylesheet which can be used for the presentation of the non-standard content. In this case the fallback-style attribute should be specified and the target stylesheet should be identified.
An Out-Of-Line XML Island may specify both a fallback item and a fallback-style.

Reading System Guidelines: Out-Of-Line XML Islands
A reading system is some combination of hardware and software. In an open market, reading systems will have a range of abilities, including the ability to handle one or more content types that fall outside the OPS preferred vocabulary.

When a reading system processes an item in the manifest which specifies a fallback item it should follow these guidelines:

Starting from an initial content document, identified in the spine or NCX, the reading system must follow the fallback chain until it finds a document it knows how to display. At the end of every fallback chain the reading system should find a document that it can render.
A reading system may display any item that it is capable of processing, it doesn't have to be the first one it finds.
If an Out-Of-Line XML Island specifies both a fallback item and a fallback stylesheet, a reading system may choose which one to use.
When a reading system is designed to have special capabilities, it may do more than the minimum with the content of an XML Island.

Inline XML Islands
When a fragment of 'foreign' XML is to be embedded in a stream of content which is written using the preferred vocabulary, the publisher should provide an inline mechanism for handling it.

We saw that fallback documents were used for Out-Of-Line XML Islands. The equivalent inline technique is the switch statement which presents zero or more case elements each of which wraps XML markup inside a required-namespace declaration. The syntax takes the form:

<ops:switch id="switch_id">
   <ops:case required-namespace="namespace">
      ... XML content in the named vocabulary
   </ops:case>
   <ops:default>
      ... fallback OPS-compliant content
   </ops:default>
</ops:switch>

A reading system should examine the required-namespace of each case element and determine whether it can handle that namespace. It should process the first such case that it finds, although it doesn't have to. If the reading system either cannot or chooses not to process any of the cases, it must process the default element. The default must always contain content that would be valid in any OPS content document.

The example below shows how a fragment of MusicXML might be presented in a content document.

<ops:switch id="musicXML_Example">
   <ops:case required-namespace="http://www.recordare.com/">
      <score-partwise version="2.0">
         <part-list>
            <score-part id="P1">
              <part-name>Music</part-name>
            </score-part>
         </part-list>
         <part id="P1">
            <measure number="1">
               <attributes>
                  <divisions>1</divisions>
                  <key>
                     <fifths>0</fifths>
                  </key>
                  <time>
                     <beats>4</beats>
                     <beat-type>4</beat-type>
                  </time>
                  <clef>
                     <sign>G</sign>
                     <line>2</line>
                  </clef>
               </attributes>
               <note>
                 <pitch>
                    <step>C</step>
                    <octave>4</octave>
                 </pitch>
                 <duration>4</duration>
                 <type>whole</type>
               </note>
            </measure>
         </part>
      </score-partwise>
   </ops:case>
   <ops:default>
      <img src="images/Cnatural.png" </img>
   </ops:default>
</ops:switch>

A reading system that understands MusicXML would probably choose to process the XML contained within the case element. A baseline reader would process the default case and render the image shown here:

Design of an NCX handler class in C#

2010-01-29T11:42:00.012Z

Figure 1. shows a revised design for the Book Content screen of the online wysiwyg epub editor I'm developing.

Figure 1. Book content and editing screen

The main changes to the design are as follows:

The TreeView display of the NCX (Table of Contents) is replaced by a Repeater control. This allows more flexibility in the management of the NCX. This post explores the functionality required by a C# class that maintains the NCX document of an epub publication; access to that functionality is achieved through the Repeater control in a way that isn't so easy with a TreeView. Each document now has a checkbox beside it, allowing the document to be selected for action.
A dropdown list of actions that can be applied to one or more selected content documents. This is the key feature that gives access to NCX management functionality and includes the following actions:
- Remove one or more content documents from the publication.
- Move a content document up or down in the reading order.
- Insert a new content document before or after a given document.
- Change the text that appears in the table of contents for a given document.
The TinyMCE editor configuration has been enriched so the author has more control over the initial styling of the text (but remember, features like selected font, font-size, and text/background colouring should be left to the reader who makes personal presentation choices when using a reading device). The new editor configuration also allows the more technical author to view the XHTML for the current content document.
When the user wants to add a content document, they now have the ability to specify the following items:

The name of the file where the new content should be written.
The document heading that should appear at the start of the content.
The text that should appear in the table of contents.

In Figure 2. the Actions dropdown list is shown expanded. This list provides the structure for much of the remainder of this post, with the addition of the following methods and properties:

A constructor that, given an NCX document, will instantiate the class.
A method for saving changes to the NCX back to disk. In the current design, changes are only written to the .epub file when the entire publication is saved.
Properties that allow the following items in the NCX to be set programmatically:
- The title of the publication in the docTitle/text element.
- The author of the publication in the docAuthor/text element.
- The unique identifier of the publication in the meta element which has a name attribute of dtb:uid
- The document publisher in the meta element which has a name attribute of epub-creator.

Figure 2. Actions on content documents

This editor application contains a class called 'ncx' which we will now examine.

Constructor
An instance of the ncx class is created by its constructor. An NCX is an XML document, so much of the functionality of NCX management is concerned with XML operations - finding individual nodes, getting and setting attribute values, managing NameSpaces etc.

The ncx constructor is given the filepath to the ncx document. This was extracted from the .epub file when the current book was selected. The <spine> element of the <package> has a toc attribute. This holds the identifier of the <manifest> item which gives the href of the NCX file. The path to this file is passed to the constructor.

The ncx document is loaded and parsed, then key nodes are extracted as follows:

<docTitle><text>Book Title</text></docTitle> - allowing the book's title to be easily read and written using the Title property.
<docAuthor><text>Author name</text></docAuthor> - allowing the book's author to be easily read and written using the Author property.
<head><meta name='dtb:uid'/> - allowing the unique identifier of the publication to be easily read and written using the Identifier property.
<head><meta name='epub-creator'/> - allowing the publisher to be easily read and written using the Publisher property.

Save
The converse of the constructor, where the NCX is read and parsed, the Save method writes the updated NCX back to disk. After it has been saved by this method, the new NCX will be saved to the .epub file the next time the publication is saved.

Remove
What does it mean to remove a content document from an epub publication? Complete removal means performing the following actions:

Delete the <item> from the <manifest>.
Delete the <itemref> from the <spine>.
Delete the <navPoint> from the <navMap> in the NCX.
Delete the content document from the file system.
Rebuild the container (.epub file).

The ncx class is concerned only with managing the NCX document, so the Remove method deletes the <navPoint> from the <navMap>. To keep the <navMap> tidy, the method also renumbers the playOrder attribute of all <navPoint> elements that came after the removed document.

Insert After and Insert Before
Authors and publishers commonly want to reorganise and rearrange content. This might involve changing the order in which content documents are presented and that is the topic of the next section. It might also involve the insertion of new content into an existing publication. As discussed above with the Remove method, adding a content document requires work elsewhere in the <package> - the <manifest> and the <spine> must also be updated.

The ncx class methods InsertAfter and InsertBefore make the required changes to the NCX document. The required behaviour is as follows:

In both cases a new <navPoint> is added to the <navMap>. The <navLabel><text> element of the <navPoint> is set to the given text. The src attribute of the <content> element is set to the given filename.
The value given to the playOrder attribute of the <navPoint> will depend on whether the action is to insert the new document before or after a selected document:
- When the new document is inserted before a selected document, the new document takes the playOrder of the selected document. The selected document and all following <navPoint> elements have their playOrder incremented to move them down the reading order.
- When the new document is inserted after a selected document, the new document takes the playOrder of the next document. That document and all following documents have their playOrder incremented, again moving them down the reading order.

Move Up and Move Down
To move a content document up or down in the reading order is relatively straightforward. The only requirement is to swap the playOrder values of two adjacent <navPoint> elements.

When a given document is to be moved up the reading order i.e. to be presented to the reader earlier, the playOrder of the given document is swapped with that of the previous document. When a document is to be moved down the reading order, it will swap playOrder values with the content document that follows it in the current reading order.

Of course, the <navMap> nodes must be sorted by playOrder before they are bound to the user interface controls. Only then will the table of contents look as expected.

The <spine> element of the <package> document also holds the linear reading order of the publication. Any changes made to the NCX should also be reflected there, but those actions are outside the scope of the ncx class.

Rename
The Rename method allows the content provider to change the text that describes a content document as seen in the table of contents. The action of this method is to store the given string in the <navLabel><text> element of the given <navPoint>.

Properties
The following properties provide convenient access to the elements and attributes of the NCX document that aren't part of the document navigation (navMap).

Title
Gets or sets the publication title, held in the <docTitle><text> element.

Author
Gets or sets the publication author, held in the &t;docTitle><text> element.

Identifer
Gets or set the unique identifier of the publication which is held in the content attribute of the <head><meta> element with its name attribute set to dtb:uid.

Publisher
Gets or sets the publisher name which is held in the content attribute of the <head><meta> element with its name attribute set to epub-creator.

Article Navigation
Developing an epub editor << Previous Next >>
Exploring epub standarda: Introduction

Online Epub Editor Project: Technical Notes

2010-01-21T13:52:00.056Z

This post adds some technical notes to the Inside Epub articles which explore the epub standards and show how to write an online wysiwyg epub editor. The following topics are covered:

Using the DotNetZip library to open and save an ebook
Checking the validity of your .epub files
Using the Sandcastle Help Builder to document code
Sorting an NCX navMap by playOrder

Using the DotNetZip library to open and save an ebook
I chose the DotNetZip library for this project because it looked well documented and seemed to offer the functionality I wanted. All was fine until I submitted an epub for validation using the facility provided by Threepress (see Checking the validity of your .epub files, below).

There were a few simple problems to resolve but the most persistent was a report that the mimetype file did not contain the expected information (application/epub+zip). The file clearly did have the correct information in it so I suspected the zipping wasn't working correctly.

The rules for the ZIP Container in the Open Container Format Specification state:

The first file in the ZIP Container MUST be a file by the ASCII name of ‘mimetype’ which holds the MIME type for the ZIP Container (i.e., “application/epub+zip” as an ASCII string; no padding, white-space or case change). The file MUST be neither compressed nor encrypted and there MUST NOT be an extra field in its ZIP header. If this is done, then the ZIP Container offers convenient “magic number” support as described in RFC 2048 and the following will hold true:

The bytes “PK” will be at the beginning of the file
The bytes “mimetype” will be at position 30
The actual MIME type (i.e., the ASCII string “application/epub+zip”) will begin at position 38

I made a couple of mistakes when building the epub the first few (many) times. Figure 1. shows one of my earlier attempts which I opened in Notepad to view the characters in the zipped file (remember it's in Zip format so you can't expect to see normal text). You can see that, although the mimetype is the first file in the archive, the file shouldn't have the long folder path 'eBookTemp/Inside epub/' and the 'application/epub+zip' doesn't start at position 38.

Figure 1. Badly constructed epub

It was clear that I couldn't simply write:

using (ZipFile zippedBook = new ZipFile())
{
zippedBook.AddDirectory(ebookPath);
}

where ebookPath was the folder holding the epub files. I had to make sure that the mimetype was uncompressed and started at the right position in the file. I evolved the following code to achieve this:

zippedBook.ForceNoCompression = true;
zippedBook.AddEntry("mimetype","","application/epub+zip");

zippedBook.ForceNoCompression = false;
zippedBook.AddDirectory(_fileSystemPath + "META-INF","META-INF");
zippedBook.AddDirectory(
_fileSystemPath + _package.PackagePath,_package.PackagePath);

zippedBook.Save(_ebookPath);

The 'ForceNoCompression=true;' ensures that mimetype is not compressed. This is followed by 'ForceNocompression=false;' to compresss the rest of the epub. With this code, the application produced an epub file that looked like Figure 2. when opened in Notepad.

Figure 2. Well constructed epub archive

This file passed the epub validation check discussed below.

The other side of the coin with respect to epub files is how to expand an epub archive so you can work with its files. I developed the following code to do this:

foreach (ZipEntry ze in zippedBook.Entries){
   ze.ExtractExistingFile = ExtractExistingFileAction.OverwriteSilently;
   if (ze.IsDirectory){
    Directory.CreateDirectory(fileSystemPath + Path.GetDirectoryName(ze.FileName));
}
else{
    ze.Extract(fileSystemPath);
}
}

Checking the validity of your .epub files
There are some important tests to perform to be sure the online epub editor is working correctly. Perhaps the most obvious is whether its output can be loaded into a reading device. That could be deceptive, though, because the reading software on one reading device might be more rigorous and compliant than on another.

Another way is to use a tool that validates epub publications. I found one of these at Threepress, as shown in Figure 3. The underlying tool is a software project called epubcheck.

Figure 3. ePub validation of Inside Epub.epub

You could argue that this is also software and it may have bugs in it, and you'd be right. Given the wide and rapidly growing range of Zip tools, epub conversion tools, and reading software around, some confirmation of compliance to standards is required and tools like epubcheck will become an important way of ensuring readers will not be disappointed.

It was a great relief, therefore, that I overcame my initial difficulties with building a conforming OCF epub file and received the big green tick from epubcheck.

Using the Sandcastle Help Builder to document code
Microsoft and others provide several tools and techniques for documenting code in the MSDN style, as in this example of the System Class Library.

When using Visual Studio, you enable XML comments on the Build tab of Project | Properties. Then you can use the triple slash (///) notation to add XML-style documentation to your source code. See Figure 4. for a sample. The comments are needed for every Namespace and for every public Class, including all its Public members - methods, properties etc. As soon as you type /// before one of these items, the Visual Studio IDE creates the comment structure with an initial <summary> and, if it's a method, with <param> elements appropriate to the method's signature.
Tools are available to extract the comments by reflection on the binary files of your application and to build navigable documentation like the MSDN example above. I've used Ndoc before so I thought I would try Sandcastle Help File Builder.

I've made a preliminary pass through the code adding XML decoration, as it's called. Figure 4. shows an example of this. There are guidelines for XML documentation comments which list and explain the appropriate XML grammar.

Figure 4. XML decoration of source code

The Sandcastle Help File Builder needed a little configuration. I set values for the following in the Project Properties:

HelpFileFormat, set to 'Website'
OutputPath, set to the folder where the output should be written.
WorkingPath, set to a folder where work files can be created.

You click on the Build icon and wait five minutes while Sandcastle works its magic. You can see the results in Figure 5. and also at Inside Epub Class Library.

Figure 5. Sandcastle 'Website' output

Sorting an NCX navMap by playOrder
The NCX document of an epub publication holds information, in XML format, about the structure of the publication. Its most important feature is a hierarchical list of 'navigation points' showing how the publication is subdivided. This list can be used by software in a reading device to provide access points allowing the reader to select directly what they want to view.

The root of the navigation data is the <navMap> element. This contains a hierarchical set of <navPoint> elements. Figure 6. shows a sample <navMap>.

Figure 6. Sample NCX showing its navMap

A <navPoint> element holds the text to be displayed to the reader in the <navLabel> element. It also tells the reading software where to go for the content document; this is held in the src attribute of the <content> element.

The topic of this Technical Note is the playOrder attribute of the <navPoint>. The playOrder attribute holds a number specifying the sequence in which the <navPoint> details should be presented to the reader.

It's important to distinguish the playOrder sequence from the sequence in which the <navPoint> nodes are held within the <navMap>; they don't have to be the same. In general, you can't assume anything about the way a content provider has built the <navMap>.

For instance, supposing a publisher is working on a 'flat' document i.e. one with only one level in the <navPoint> hierarchy. If a new content document needs to be inserted between two documents with playOrder values of 5 and 6, the publisher might add the new <navPoint> as the last node in the <navMap>; they would give the new <navPoint> a playOrder value of 6, and increment the playOrder of all <navPoint> elements that need to follow it in reading order.

What this means is that before presenting the navigation details to the reader, the <navPoint> nodes need to be sorted by their playOrder attribute. There are several approaches that could be taken, but the one described here is to use an XSL transform.

The following listing shows one possible transform.

1   <?xml version="1.0" encoding="utf-8"?>
2     <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
3      <xsl:output method="xml" indent="yes" omit-xml-declaration="no" encoding="utf-8"/>
4      <xsl:template match="node()[local-name()='navMap']">
5           <xsl:element name="navMap">
6               <xsl:apply-templates select="node()[local-name()='navPoint']">
7                <xsl:sort select="number(@playOrder)" data-type="number"/>
8              </xsl:apply-templates>>
9           </xsl:element>
10      </xsl:template>
11      <xsl:template match="node()[local-name()='navPoint']">
12         <xsl:copy-of select="."/>
13     </xsl:template>
14 </xsl:stylesheet>

At line 3, the <xsl:output> statement declares that the output is to be an XML document which includes an <?xml ?> declaration and is encoded in UTF-8.

Lines 4-10 of the transform find and process the <navMap> element.

At line 5 a new <navMap> is generated in the output.

At line 6, the transform handles the <navPoint> elements. The corresponding template at lines 11-13 returns a copy of each <navPoint>.

Line 7 is the key to the whole transform. It sorts the returned <navPoint> elements using the playOrder attribute.

The end result is a <navMap> in which the <navPoint> elements are in the order in which they should be presented to the reader.

Calling the transform in C#
The calling sequence for using this transform in C# can be something like the following:

// load the transform into an XslCompiledTransform instance
XslCompiledTransform xslt = new XslCompiledTransform();
xslt.Load(MapPath(".") + "/TransformNavMap.xsl");

// prepare an XmlWriter to write the transform output
StringBuilder newNavMap = new StringBuilder();
XmlWriter writer = XmlWriter.Create(newNavMap , xslt.OutputSettings);

// sort the book's navMap using the transform
xslt.Transform(book.container.package.ncx.NavMap, writer);
writer.Close();

Now the new <navMap> can be retrieved as an XmlDocument using newNavMap.ToString();

User interface for an online epub editor

2010-01-19T17:38:00.002Z

This article looks at the minimum requirements for an online epub editor and how they have been implemented in the sample application. The scope is limited to handling the editor's functionality - how to create, save, edit, and view .epub publications. It excludes the supporting features like user login, disk space management, uploading and referencing images. Those are important topics but they are common to many online applications, so I don't want to reinvent them here.

Requirements Summary
To refine further the scope of this project, an epub editor should include the following abilities:

Select an existing epub book for viewing or amendment.
Open a selected epub book and view its contents - including its metadata.
Navigate around a book using its NCX table of contents.
Edit a section and save its contents.
Add a new section to the book.
Remove a section from the book.
Change the reading order of the content documents.
View the book's metadata.
Edit and save the book's metadata.
Save the book to its .epub file.
Create a new epub book.

Not included, for this first version of the editor, are:

Adding multiple instances of metadata items, such as title, identifier, language, creator, etc.
Implementing Save As to an .epub with a different name.

Application Overview
Figure 1. shows a screenshot of the online editor. A menu gives access to different views of the application. It has options called:

Books - showing a list of epub books in the user's 'library'.
Book Information - displaying the metadata for the selected book.
Book Content - displaying the table of contents for the selected book.
Media - listing the non-text media items (e.g. images) that are part of the selected book.
Styles - listing the CSS files that are associated with the selected book.

Figure 1. Viewing a list of books

Select an existing epub book for viewing or amendment
Figure 1. shows the application positioned on the 'Books' view. The screen below the menu comprises a ListBox and a button showing the text 'New epub'.

The ListBox displays the .epub files that are in the user's library, where 'library' is defined as a folder on the web server that hosts the application. In this example, I've added an item to the <appSettings> in the web.config file of the application which provides the path to the library folder. This is shown in Figure 2.

Figure 2. epub library configuration

When the user selects a book, by clicking on it in the list, the application reads the .epub file using the ZipFile entity of the DotNetZip library. Using the ExtractAll method of that class the contents of the .epub are written to the file system. All subsequent operations, like changing a document or adding a document, are carried out on files rather than on the in-memory zipped data. However, the .epub file is kept upto date after each saved change.

In a multi-user application a more sophisticated approach would be required to keep each user's library separate from all others and under the protection of an access control mechanism. There are similarities with blogging sites and Content Management Systems.

The 'New epub' button, unsurprisingly, is where the user will start creating a new epub publication from scratch.

Viewing and changing metadata
Figure 3. is a screenshot after the user selects a book and then clicks on the 'Book Information' tab.

Figure 3. epub metadata

The application displays the metadata items that are found in the <metadata> section of the book's package document. The display is created using an ASP.Net Repeater control which is bound to the <metadata> node, so it displays all of the items found there and only the items found there. Further, it displays them in the order in which they appear, so the two <date> elements for instance are not together.

Edit and save a book's metadata
The information is displayed in TextBox controls, so it can be changed. The 'Save' button is used to update the metadata in the package document. We'll see later how the application saves the package data in the .epub file.

Some enhancements are needed to this model for a more flexible editor. For instance:

The ability to mark an entire .epub as read-only is desirable. If you don't own the intellectual property to a work, it's not appropriate to change it.
Some metadata items can occur more than once. Examples are: title, identifier, language, creator, contributor. It would be useful to be able to add and remove such items in the metadata.

Navigate around a book using its NCX table of contents
Figure 4. shows a screenshot similar to one in an earlier post and is the result of clicking on the 'Book Content' tab while a book is selected.

Figure 4. Navigating a book's contents

This screen uses a TreeView control to show a hierarchical table of contents. The TreeView is bound to a version of the navMap extracted from the book's NCX information. To the right of the table of contents is the area used to view and edit the text. This is a TextBox control associated with the tiny MCE Javascript, converting it into an editor control.

Edit and save content and add a new section
Beneath the reading/writing area in Figure 4. you can see the following controls:

A button marked 'Save'. This is used to save the current contents of the edit area to the underlying content document in the file system.
A button marked 'Add' accompanied by two TextBoxes labelled 'Name' and 'Title'. The user enters the name for the content document in the Name box and the content heading in the Title box and clicks the Add button.

Figure 5. shows the results when Name is set to 'chapter01' and Title is set to 'Chapter 1'.

Figure 5. Navigating a book's contents

An empty content document called 'chapter01.xml' is created and the text 'Chapter 1' is inserted into the document heading. The application adds chapter01 to the package, meaning the content document is added to the <manifest>, the <spine>, and the <navMap> in the NCX document. The application navigates to the new document ready for the user to start typing. In this case, the user has typed some text into the editing area and pressed 'Save'.

Creating a new epub publication
It was shown above that there is a 'New epub' button on the 'Books' tab. Figure 6. shows the result of clicking that button.

Figure 6. Creating a new epub

The user is presented with a set of TextBoxes inviting input of basic metadata for the new book. The first three items - title, identifier, and language - are mandatory. The only item already set to a value is the identifier. In case you don't have your own ISBN number or other number that is globally unique, the application generates a GUID (Globally Unique IDentifier). You can use this or overwrite it with your own number.

Figure 7. shows the screen after each metadata item has been given a value and just before the 'Create' button is clicked.

Figure 7. metadata for the new epub

Figure 8. shows the results of clicking the 'Create' button. A new epub is created and the application shows the 'Book Contents' view. The user has entered and saved some text. Notice this is an almost empty publication, having only one content document.

Figure 8. The new epub waiting to be written

Figure 9. shows the 'Books' view after a new book is created. The list of books is updated to show the new title. Clicking on the new book opens it for viewing and editing just like any other book in the library.

Figure 9. New epub showing in the 'Books' list

Summary
This article has given a view of how an online wysiwyg epub editor might look. Details of the code can be found, shortly, in the reference section for the code project.

Undoubtedly, this is rough and ready. Many refinements would be required to make using this application a useful and pleasant experience. Among these are:

A much richer configuration of the tiny MCE editor to provide better formatting of the text.
Autosaving contents at short intervals.

Article Navigation
Developing an epub editor << Previous Next >>
Exploring epub standarda: Introduction

Develop your own epub editor

2010-01-14T15:05:00.005Z

The previous posts in this series explored the structure of epub books and demonstrated how the epub standards work together to describe and package content documents. If you found those articles highly technical you might want to look away now - this post is the first of a series that shows how to create your own web-based, wysisyg editor that you can use to create epub documents. The programming strand of Inside Epub starts here. This post is an introduction to the subject and gives an idea of the development environment, the software tools, and the documentation that will be available as the project unfolds.

There are still topics to cover in the previous strand, like embedding XML islands in your content and handling fallback from non-standard to standard document types - and I will cover those in future. To help you choose the posts that match your interests, I've created a separate list of links for the code development and will join the posts in each strand with 'next' and 'previous' links.

Objectives - mine and yours
The aim of the programming strand of this blog is to create a web-based, wysiwyg epub editor. This will work only with epub documents and will be suitable for the creation of new ebooks. There's plenty of effort going into conversion of existing texts between formats so I don't feel the need to do that. If you believe that epub will become the format of choice for ebooks then why not create your book in epub directly? I don't claim that this application will be as powerful as Microsoft Word® with a 'Save As epub' add-in; it definitely won't be. My aim is to show you how you might set about creating a robust, online, multi-user epub editor.

To show you where we'll end up, Figure 1. shows a screenshot of the editor after opening the sample epub book The Curious Case of Benjamin Button. It has a menu across the top and the body of the page shows the result of selecting a book on the 'Books' tab and clicking on the 'Book Content' tab. This manages to look like Adobe Digital Editions but, being online, doesn't require you to download and install the reader.

At the moment we're not interested in style, only in functionality. If you want to see what might be possible by adding CSS styling, look at epub Zen Garden.

Figure 1. Web-based, wysiwyg epub editor

The application was written for the ASP.Net platform using Microsoft's Visual Web Developer 2008 Express Edition®. The programming language is C#.

On the left of the screenshot, a Treeview control is bound to the navMap of the NCX document in order to display the Table of Contents. To the right, an editor control shows the content of the Title Page.

Software Prerequisites
We've seen that epub publications are held as Zip archives and that epub packaging is achieved using a range of XML documents. Content documents are held in XHTML. To start developing an epub editor that runs on the .Net platform I chose the following range of free and/or open software tools:

Visual Web Developer 2008 Express Edition is used as the main development platform. There are more recent versions of this toolkit available, in beta testing at the time of writing, if you must have the latest. The tool enables the development of ASP.Net websites and includes extensive XML handling. The NCX file requires transformation before it is bound to the Table of Contents control and Visual Web Developer has facilities for using XSLT transforms.
DotNetZip library is used to manipulate Zip files in the C# .Net environment. Follow the stratightforward installation instructions. The ZipFile class of this library is used to open .epub files and to extract the contents to a folder on disk. It is also used to refresh the archive when a content document is changed or when documents are added or removed.
tiny MCE is a widely used Javascript editor which converts an ASP.Net TextBox control into an editor that outputs XHTML documents. The WordPress blogging site and the Joomla Content Management Software use this technology. The installation instructions are easy to follow. Configuration is a bit harder so, for the purposes of these posts, I'm keeping it simple.

Prototyping Approach
My favourite approach to using visual development tools is prototyping and this is especially true if I just want to demonstrate some techniques. It's really easy to throw a website together using Visual Web Developer but, having said that, the object-oriented approach required by C# means we need to give some thought to the classes of object that will be required.

Data Model
Figure 2. shows the data model for an epub document drawn, literally, on the back of an envelope.

Figure 2. epub data model

Each node in this model will be developed either as a C# class or will be accessible as an XMLNode within one of those classes.

Example Class epub
Figure 2. shows the class epub which is used to model the contents of an epub file. Most of the code is hidden in this image to enable you to see the structure. The class has Members, Constructors, Methods, and Properties.

Figure 2. epub class

In order not to clutter the posts in this thread, reference material for the code project, including class definitions, can be found at: Inside Epub Code Reference

That's it for setting the scene. Next time I'll look at the user interface.

Article Navigation
Developing an epub editor << Previous Next >>
Exploring epub standarda: Introduction

Inside Epub Code Reference

2010-01-14T14:48:00.001Z

Documentation for the Class Library developed for this project is available at www.hazelhurst.net/insideepub/

Class epub

2010-01-14T14:41:00.002Z

This class models an epub ebook. The approach is taken that the Zip handler will be used only to open and save a .epub file. All other operations will use the files in the folder to which the Zip file is extracted.

epub Members
Class epub exposes the following members:

Property	Description
_container	_container is a private instance of class container. It gives access to the rest of the epub documents in the ebook, mainly through its package instance.
_filePath	_filePath is a string holding the location in the file system where the .epub for this instance of epub is located.

epub Constructor
The class has a constructor with the signature:

public epub(string ebookPath, string fileSystemPath)

This allows the caller to create an epub instance which will locate and open the ebook at location ebookPath. The ebook is extracted from the .epub and written to the file system at location fileSystemPath.

epub Methods
Class epub exposes the following methods:

Method	Description
Create	Creates a new epub ebook with the given title at the given location. Uses the given working folder path to store the files that will be zipped into the .epub.
Open	Open an existing .epub file and expand it into the given working folder.
Save	Save the epub instance as a .epub file at the given location.
SaveEntry	Save the given text of a content document.

epub Properties
Class epub exposes the following properties:

Property	Description
container	Get or set the container instance belonging to the current instance of epub. This property is widely used to gain access to most of the ebook's package and NCX data.

Code of the epub class (14Jan10 14:20)
The code of the epub class is shown below.


#region using
using System;
using System.IO;
#endregion

namespace net.hazelhurst.epub
{
public class epub
{
#region Members
private container _container;
private string _filePath; 
#endregion 

#region Constructors
public epub(string eBookPath, string fileSystemPath)
{
Open(eBookPath, fileSystemPath);
} 
#endregion

#region Methods
public static epub Create(string title, string booksPath, out string workPath)
{
epub result = null;
string emptyBookPath;

workPath = booksPath + title + "\\";
if (!Directory.Exists(workPath) && !File.Exists(booksPath + title + ".epub"))
{
string newbook = booksPath + title + ".epub";
emptyBookPath = booksPath + "empty\\";
File.Copy(emptyBookPath + "empty.zip", newbook);
result = new epub(newbook, workPath);
result.container.package.Title = title;
}
else
{
throw new Exception("A book with that title already exists");
}
return result;
} 
public bool Open(string eBookPath, string fileSystemPath)
{
bool bookOpen = false;

_filePath = eBookPath;

// get the book's container
_container = new container(eBookPath, fileSystemPath);

// if the container is available
if (_container != null)
{
bookOpen = true;
}

return bookOpen;
}
public bool Save()
{
bool result = false;
_container.Save();
//ZipFileHandler.Save(Title, filePath, outputPath);
return result;
}
public bool SaveEntry(string fileName, string content)
{
bool result = false;

try
{
_container.SaveEntry(fileName, content);
}
catch (Exception ex)
{
throw ex;
}
return result;
}
#endregion

#region Properties
public container container
{
get
{
return _container;
}
set
{
_container = value;
}
}
public string Title
{
get { return _container.package.Title; }
set { _container.package.Title = value; }
} 
#endregion

} //epub
}

OPS and PDF in one OCF container

2010-01-06T18:00:00.005Z

I showed you what an OCF container file looked like in the topic: How the standards work together. Here it is again:

Figure 1. Container with one <rootfile> element

The container is always called container.xml. The example has a <rootfile> element in it that points to the OPF package file ebp.opf in folder OPS. That folder also holds all of the other items in the manifest.

A key strength of epub is that it delivers text that will fit easily on any size of reading device, from the smallest smartphone to the largest PC monitor. Text will flow smoothly from one screen to the next regardless of the size of screen or the size of font that the reader prefers.

Supposing you want to give the reader the ability to print the book in an attractive format. PDF would be a good choice for this. Sites like Smashwords offer separate downloads of epub and PDF versions of a book, but they could be bundled together using the Open Container Format. The OCF is a general-purpose container specification and you can store more than one version of your publication in it.

Figure 2. shows container.xml for a sample book available in the IDPF forums. The book contains some Sherlock Holmes stories and Figure 2. shows how two renditions of the text - OPS and PDF - are represented:

Figure 2. Container with two renditions

Quite simply, there are two <rootfile> elements present, one for each rendition:

<rootfiles>
<rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
<rootfile full-path="PDF/Holmes.pdf" media-type="application/pdf"/>
</rootfiles>

The first <rootfile> identifies the OPF package, as in the earlier example. Reading software designed to handle OPF packages would render the book using information contained in this <rootfile>.

The second <rootfile> points to the file Holmes.pdf in folder PDF and the media-type indicates that this should be handled as a PDF file. Here, then is the alternate rendition for the text. Notice that the container follows the OCF recommendation that alternate renditions should be placed in dedicated folders. Figure 3. illustrates this by showing the folder structure in a WinZip® view of the epub file.

Figure 3. Dedicated folders for alternate renditions

The PDF file is held in a distinct folder in the Zip archive.

Not now, but in the future, you may be able to store more than one publication in an OCF container, for example the complete works of an author held as separate ebooks. This would require the reading software to read the container and present the list of contained ebooks to the reader.

Article Navigation
Next >>

NCX navigation in epub books

2010-01-05T16:00:00.001Z

We saw in an earlier post how the <spine> element in the package document is used to provide a linear reading order for the content documents of an epub publication. An ebook reader could use the spine data to retrieve and chain together the book's content documents and present them to you, starting at the first screen of the first document.

But, suppose you're looking at Victor Hugo's Les Misérables and you want to find the passage where Jean Valjean is carrying the wounded Marius through the sewers of Paris. How to find it? You don't want to scroll forwards through the book from the beginning (my Penguin Classics version has 1200 pages and I'd be looking for page 1083). What you need is a Table of Contents that would guide you to Part Five, Book III, Chapter III. The epub specifications make this possible through the use of an XML document that follows yet another open standard.

The DAISY Consortium and NCX
The Digital Accessible Information System consortium is an organisation aiming "to lead the worldwide transition from analog to Digital Talking Books." As such, they have been heavily involved in developing and maintaining information standards. The DAISY/NISO standard entitled DAISY Specifications for the Digital Talking Book is the basis of the approach taken by the International Digital Publishing Forum (IDPF) to providing a Table of Contents in an epub publication.

The standard has an acronym. It's called NCX. The Open Packaging Format specification offers two meanings for the acronym:

Navigation Center eXtended
Navigation Control for XML applications

Take your pick, it doesn't really matter. The important thing is that the standard is followed. To give you immediately an idea of how NCX can be used to present a Table of Contents, take a look at Figure 1.

Figure 1. NCX for The Curious Case of Benjamin Button

The screenshot in Figure 1. shows the NCX document that's shipped with the epubBooks version of The Curious Case of Benjamin Button. In this view, I've collapsed the <head>, <docTitle>, and <docAuthor> elements in order to concentrate on the <navMap> information.

A simple NCX example
A book can be said to have a hierarchical structure - it may have Parts which comprise Chapters which in turn may be divided into Sections and Sub-sections. This hierarchy is expressed in the navMap section of the NCX document. Starting with our simple example, which has no hierarachy to speak of, take a look at Figure 2, below.

<navMap>
   <navPoint id="navpoint-1" playOrder="1">
      <navLabel>
         <text>Title Page</text>
      </navLabel>
      <content src="title.xml"/>
   </navPoint>
   <navPoint id="navpoint-2" playOrder="2">
      <navLabel>
         <text>epubBooks Information</text>
      </navLabel>
      <content src="epubbooksinfo.xml"/>
   </navPoint>
   <navPoint id="navpoint-3" playOrder="3">
      <navLabel>
         <text>1</text>
      </navLabel>
      <content src="chapter-001.xml"/>
   </navPoint>

Figure 2. A simple navMap

The <navMap> element can have any number of <navPoint> elements. Each <navPoint> identifies a significant subdivision of the book to which the reader may navigate directly - for instance to the start of a given chapter. The <navPoint> element has attributes 'id' and 'playOrder'. 'id' is a unique identifier and 'playOrder' is a number, starting from 1, that indicates the position of the navPoint in the sequence of content documents making up the publication.

A <navPoint> element contains a <navLabel> element and a <content> element. The <navLabel> has a <text> element which holds the text that will be displayed in the Table of Contents. The <content> element has 'src' attribute that tells the reading software the name of the content document to display.

Figure 3. shows The Curious Case of Benjamin Button opened using Adobe Digitial Editions®. You can see how the <text> values from each <navPoint> are displayed in the Table of Contents.

Figure 3. NCX Table of Contents in Adobe Digital Editions®

When the reader clicks on chapter 1, represented by the imaginatively selected "1" in the Table of Contents, the reading software looks up the <content> element of that <navPoint> and fetches 'chapter-001.xml' for display.

An NCX with two levels
A <navPoint> may itself contain further <navPoint> elements. That is how the hierarchical structure of the book is expressed. In the simple example above the nesting is only one level deep, but take a look at Figure 4.

<navPoint id="navpoint-3" playOrder="3">
   <navLabel>
      <text>PART ONE</text>
   </navLabel>
   <content src="part-01.xml"/>
   <navPoint id="navpoint-4" playOrder="4">
      <navLabel>
         <text>CHAPTER I</text>
      </navLabel>
      <content src="chapter-001.xml"/>
   </navPoint>
   <navPoint id="navpoint-5" playOrder="5">
      <navLabel>
         <text>CHAPTER II</text>
      </navLabel>
      <content src="chapter-002.xml"/>
   </navPoint>

...intervening navPoints in Part One

</navPoint> (end of navpoint-3)

Figure 4. navPoints nested to two levels

The NCX extract in Figure 4. is taken from Jules Verne's 20,000 Leagues Under the Sea, also downloaded from epubBooks. I've changed the colour coding of the elements to show the hierarchical relationship between the navPoints.

navPoint-3 introduces Part One of the book. As before, it has a navLabel (PART ONE) and the content document is called 'part-01.xml'. Next is another navPoint within the Part One navPoint i.e. before the </navPoint> declaration. This indicates that the new navPoint and all of the navPoints up to the next </navPoint> belong to Part One of the book. Figure 5. shows how this looks in Adobe Digital Editions®

Figure 5. Two-level NCX

Notice how the chapter titles are indented within PART ONE. The standard does not impose any limit on the depth of nesting so if you're a corporate lawyer drawing up an eContract you can create sub-sections to your heart's content. Also, NCX doesn't impose names like part, chapter, and section to the structure of a book. It's left entirely to the publisher how they want to name these subdivisions; the NCX document holds whatever you choose in the navLabel/text entries.

Ebooks are nothing without the writing
To finish off this topic, I went and found my all-time favourite book, Les Misérables, and opened it in Adobe Digital Editions to locate that passage I mentioned earlier. Figure 6. Shows how epubBooks built the NCX for this book. They have three levels of nesting, dividing the work into Volumes, Books, and Chapters.

Figure 6. Jean Valjean carrying Marius

A closer look at OPF

2010-01-04T15:09:00.012Z

Let's take a closer look at the Open Packaging Format.

Recall from the previous post that an electronic publication conforming to the OPF standard must provide a package document. This must be an XML document with a root element of <package> which includes elements called <metadata>, <manifest>, and <spine>. Figure 1. shows an overview of the package document that is delivered with our sample epub ebook.

Figure 1. Package Overview

You can see this document has the correct set of package elements. Before looking at each in detail, there are two things I'd like to point out on this screenshot. First, the unique-identifier attribute in the <package>:

unique-identifier="EPB-UUID"

This attribute tells the software of the reading device to look out for a metadata item of type <dc:identifier> that has an 'id' attribute with the value 'EPB-UUID'. The value of this element is an identifier that is globally unique. Towards the bottom of the metadata, when we look at it, you will find the following element:

<dc:identifier id="EPB-UUID">
urn:uuid:CBC56AFC-6C29-1014-8672-92A1DF1F0AF1
</dc:identifier>

That 32-digit hexadecimal value is the GUID (Globally Unique Identifier) generated by epubBooks to identify this particular publication. Of course, an ISBN is another globally unique identifier, and if you are in the publishing business and routinely buy ISBNs by the dozen, you would probably insert the ISBN here.

Second, the attributes in the <metadata> element:

xmlns:opf="http://www.idpf.org/2007/opf"
xmlns:dc="http://purl.org/dc/elements/1.1"

indicate that the prefix 'dc' refers to the Dublin Core element definitions (see below for more detail), and that the 'opf' prefix refers to OPF extensions to the Dublin Core. For instance, look at the two date elements in the metadata:

<dc:date opf:event="original-publication">1922</dc:date>
<dc:date opf:event="epub-publication">2009-09-24</dc:date>

The 'dc' prefix on the 'date' elements identifies them as publication dates that follow the Dublin Core specification. The 'opf' prefix on the 'event' attribute identifies 'event' as belonging to the OPF specification.

Unfortunately, looking at the OPF specification, it seems the publisher is free to give the event attribute whatever value they like:

"The set of values for event are not defined by this specification; possible values may include: creation, publication, and modification."

Now, let's look in more detail at the package metadata.

Package <metadata>
The <metadata> element of the package can contain wide ranging information about the publication. To keep OPF as open as possible, the metadata of an OPF package makes use of another open standard, namely the Dublin Core Metadata standard.

The Dublin Core is an initiative working towards standard ways of describing resources. They actively promote standardised sharing information thereby increasing interoperability between organisations - let's all agree to call a spade a spade and not a shovel or a digger.

The Dublin Core has a wider scope than just ebooks. However, there is a rich set of attributes that can be applied to electronic publications. Figure 2. shows the metadata that epubBooks placed in the package of The Curious Case of Benjamin Button.

Figure 2. Package Metadata

For convenience, I'll list the metadata elements again here:

title
language
identifier
---------
creator
date(s)
publisher
subject
source
rights

The elements above the dashed line are mandatory. The OPF Package Schema says that there must be at least one title, at least one language element, and at least one identifier element. All other elements are optional.

Title
In fact the schema says there must be 'One Or More' of the mandatory elements. In other words, there can be more than one title, more than one language, and more than one identifier. The standard does not specify which title should be displayed, only that a reading device should choose 'the most appropriate title' for display, perhaps based on available fonts or language.

Identifier
There can also be more than one identifier element in the metadata. We've seen above how the unique identifier is handled. If you wanted, you could publish an ebook with several identifiers: your internally generated identifier, a GUID, and your ISBN. You then have to say which is to be considered the globally unique identifier.

Language
The specification says there must be at least one <language> metadata element, but there may be more than one. I suppose if you were publishing an English-Mandarin dictionary or were writing a learned text about the Rosetta Stone you might have a reason to specify more than one language.

Full list of metadata elements
The following table summarises the full set of metadata elements that can appear in the <metadata> section of a <package>

Element	Number	Description
title	One or more	The title of the publication. As we've seen, there can be more than one, but there must be at least one title.
creator	Zero or more	The primary creators or authors of the publication. Each element is recommended to hold one name and is recommended to be in the form it should be presented to the reader. When there's more than one creator, it's expected they would be displayed in the order in which the elements appear in the metadata. Other contributors should be identified in <contributor> elements.
subject	Zero or more	The subject matter of the publication. There is no standardisation here. The optional text could be a sentence, a list of keywords, or one keyword per element.
description	Zero or more	The description(s) of the publication.
publisher	Zero or more	The publisher(s) of the publication.
contributor	Zero or more	The person(s) making contributions to the publication in a manner that is secondary to the role of creator. OPF defines nearly 30 different roles as contributor and specifies the syntax for their identification.
date	Zero or more	The publication date(s) for the publication. We've already seen that OPF extends the Dublin Core definition of this element, allowing different 'event' dates to be recognised.
type	Zero or more	The type(s) that describe the publication. This is relatively free-form although the specification recommends using words from controlled vocabularies i.e. selecting from a restricted set of words. Terms relating to genre e.g. Young Adult, Fantasy, Literary, might be used as well as terms like Fiction, Non-Fiction etc.
format	Zero or more	The media-types of the publication. The recommendation is to use a MIME type.
identifier	One or more	One or more identifiers for the publication, one of which must be defined as a unique identifier. See the discussion above.
source	Zero or more	Identification of any other documents or publications from which the current publication is derived.
language	One or more	One or more language identifiers.
relation	Zero or more	Identifier(s) of resources to which the current publication is related.
coverage	Zero or more	One or more identifiers of the scope of the publication. OPF recommends following the Dublin Core specification of coverage and to use a controlled vocabulary for geographical, temporal, and juridical descriptions.
rights	Zero or more	An assertion of the rights of the publisher/creator with respect to this publication.

Table 1. Package metadata elements

Package <manifest>
Figure 3. shows the <manifest> element of the OPF package for our sample epub ebook, The Curious Case of Benjamin Button.

Figure 3. Package Manifest

The package manifest identifies all of the resources that are needed to display the ebook fully and correctly. Each entry in the manifest consists of an <item> element, as in:

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

Each <item> element has an 'id' attribute which identifies this resource uniquely within the publication. It has an 'href' attribute which points to the content document, in the example above it's an XML document called 'chapter-001.xml'. The 'media-type' attribute in this example shows that the resource should be handled as an XHTML document.

You can see that the manifest lists 13 content documents: a title page, a page of information about the publisher (epubBooks), and the 11 chapters of the story.

Each content document includes a 'link' element that refers to the CSS stylesheet 'body.css'. Therefore, the manifest includes an <item> for it:

<item id="main-css" href="css/book.css" media-type="text/css"/>

The publisher information document, epubbooksinfo.xml, includes an image which is the company logo. Therefore, the manifest includes an <item> for it:

<item id="epubbooks-logo" href="images/epubbooks-logo.png" media-type="image/png"/>

The rule is: if the content documents use it, it must be in the manifest. There are some aspects of the manifest that will be reserved for a future post so they don't clutter up this presentation. These cover media-types that are not part of the OPS Core, Out-Of-Line XML Islands, and the use of fallback documents to support these non-standard documents.

There's one more item in the manifest, and it's quite an important one:

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

The 'id' attribute is set to 'ncx', the 'href' points to a file called 'epb.ncx', and the 'media-type' indicates that the resource should be handled as an NCX document. NCX is a standard way of declaring a Table of Contents. It's another open standard, this time maintained by the DAISY consortium.

This leads us nicely into the description of the third mandatory element of an OPF package - the <spine> element.

Package <spine>
Figure 4. shows the expanded <spine> element of our sample package.

Figure 4. Package Spine

The <spine> starts off like this:

<spine toc="ncx">
   <itemref idref="titlepage" linear="yes"/>
   <itemref idref="epubbooksinfo" linear="yes"/>
   <itemref idref="chapter-001" linear="yes"/>
   <itemref idref="chapter-002" linear="yes"/>

The element has a 'toc' attribute with the value 'ncx'. This is the value of the 'id' attribute of the item in the manifest that points to the mandatory table of contents document. In other words, it's a way to identify the table of contents. We saw in the last section that the manifest item with an id of 'ncx' points to a document called 'epb.ncx'. We'll look at NCX documents in more detail in a future article.

The next thing to notice about the <spine> is that it contains a list of <itemref> elements. Each <itemref> has an attribute called 'idref', and the value of an idref is the id of an item in the manifest.

For example, the first idref has value 'titlepage'. Look back at the manifest screenshot and you'll see that the first content document in the manifest has id="titlepage", and that item points to the content document itself (titlepage.xml).

The spine is a list of content documents and the important thing about the list is that it specifies the linear order in which the content documents should be displayed: title page, followed by the publisher's information page, followed by chapter 1, etc.

The <itemref> element has an optional attribute called 'linear'. This attribute takes a yes/no value and is used to indicate whether the referenced document is primary or auxiliary. This can be used by reading devices to show auxiliary information in a different way from the main flow of the primary information. In our case, the values are all set to 'yes' which is the default.

How the standards work together

2010-01-03T12:15:00.116Z

In earlier posts I've referred to the Open Publication Structure, the Open Container Format, and the Open Packaging Format. What helps to make these specifications open is that they make widespread use of other, industry-wide, open standards like XHTML, XML, CSS, MIME, among others.

The IDPF standards documents make frequent reference to these other standards, and they all work together to make it possible for content providers - authors and publishers - to ensure that their publications are available on the widest range of reading devices. All they have to do is to create documents that conform to the standards. Likewise, hardware and software developers know that if they also follow the standards their reading devices will be able to display all conforming publications.

Three Standards
If you looked at the IDPF website you might be wondering why there are three standards documents for epub publications. The reason is that they address different aspects of an electronic publication. It's widely recognised in the industry that features like content and presentation should be stored separately. Just as content is stored in XML and presentation is stored in CSS, what is packaged in an epub document is described separately from how it is packaged.

Book Analogy
Imagine for a moment that you have in your hand a first edition copy of The Curious Case of Benjamin Button. The words that Fitzgerald used belong to a vocabulary - the English language. The Open Publication Structure defines the 'Preferred Vocabulary' of epub Content Documents - not the words you use to write a book, rather the XHTML elements that you use to create the structure of the book, building it into sections, chapters, and parts.

The paper book has several chapters that are printed in order (we hope). The book also has a title page and other items that are not part of the story but which book designers call Front Matter (Foreword, Preface, Acknowledgements etc.). The book may also have a Table of Contents in the Front Matter which helps the reader find their way around the content. The Open Packaging Format defines how all of these parts of an epub document should be described.

Finally, the book has a cover which binds the content into a single entity, as opposed to loose pages or separately bound chapters. The Open Container Format specifies how the electronic Package, which is all of the necessary information for the book to comply with the epub standards, is held as a unit. In abstract terms the output of this bundling together is called a Container. On your computer it might be represented as a folder in your file system or, as in our case, a Zip archive held in one file with the .epub extension.

Open Publication Structure
The Open Publication Structure is mostly concerned with which XHTML elements you can use to build a content document. Let's take a look at what we mean by a content document. The following image shows one of the shorter chapters from our sample ebook The Curious Case of Benjamin Button.

Figure 1. Sample Content Document

You can see from the first line that a content document is an XML document. The next declaration says that it contains an XHTML document which means it contains a version of HTML that can be held as valid XML.

If you're not sure about XML, take a look at the XML Tutorial at W3Schools

This is followd by the XHTML content itself. You can see the usual <html>, <head>, and <body> elements that make up an XHTML document. Let's look at the contents of the <head> element first:

<link rel="stylesheet" href="css/book.css" type="text/css"/>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8"/>
<meta name="EPB-UUID" content="CBC56AFC-6C29-1014-8672-...">

The <head> contains a <link> element that points to the external stylesheet called 'body.css' which can be found in the css folder. It also contains a <meta> element which declares that the content type of the document is 'application/xhtml+xml' and that the character encoding is UTF-8.

Now take a look at the <body> of the document:

<div class="body">
   <div class="chapter">
      <h3 class="chapter-title">6</h3>
         <p>When, six months later, the...</p>
         <p>The Sunday supplements of...</p>
         <p>However, every one agreed with...</p>
         <p>On the part of the two people most...</p>
      </div>
</div>

The <body> element contains two <div> elements, each with a different class, so that appropriate CSS styling will be applied. It contains a chapter title with <h3> styling, and four paragraphs elements (<p>).

What the Open Publication Structure tells you is which XHTML elements you can use to build a content document. The following extract from the standard shows how the elements we've just seen are defined as required elements that all conforming epub reading software must accept and render.

XHTML 1.1 Module Name	Elements
Structure	body, head, html, title
Text	abbr, acronym, address, blockquote, br, cite, code, dfn, div, em, h1, h2, h3, h4, h5, h6, kbd, p, pre, q, samp, span, strong, var
Meta-information	meta
Link	link

Table 1. Extract of Open Publication Structure Preferred Vocabulary

The standard refers to XHTML Module Names because XHTML can be subdivided into areas of functionality called Modules. This allows designers and developers to know what they can use and what they might find in a document that allows or requires the use of a given Module.

There is a lot more to write about Open Publication Structure, but this introduction serves to show that, at its simplest, it specifies what can go into a content document.

Open Packaging Format
The Open Packaging Format is a standard that defines how the contents of an epub electronic publication are identified and specifies how they should be presented. Recalling the post First look Inside an epub ebook, there's a file in the Zip archive called 'ebp.opf'. That .opf extension indicates that the file contains Open Packaging Format information.

In Figure 2. I've extracted ebp.opf from the Zip and renamed it as ebp_opf.xml. Then I've loaded the XML file into Visual Web Developer 2008 Express Edition and collapsed all but the root node and the first level of child nodes. This gives an overview of the package document.

Figure 2. Package Overview

The <package> node has three child nodes:

A <metadata> node which holds a range of information about the publication as a whole. This list is quite long and includes such information as: title, creator, subject, description, publisher, creator.
A <manifest> node which holds descriptions of every file making up the publication. The manifest lists all of the content files, style sheets that are referenced, and all images that are included in the content.
A <spine> node that includes an ordered list of the content documents, effectively defining their reading order or the order in which they will be displayed by a reading device.

We'll look in more detail at these elements in a future post, but notice that the <spine> node has a 'toc' attribute. 'toc' stands for Table of Contents, and the value of this attribute is the unique identifier (id) of the document that contains the table of contents. In our example the value is 'ncx'. This means that the manifest will include an item which has an 'id' attribute set to "ncx" and the file that this item points to should be treated as the Table of Contents for the publication.

Open Container Format
Finally in this post giving an overview of how the IDPF standards work together, we'll take a quick look at the Open Container Format. Remember from the book analogy how the container binds all of the package contents together. The OCF defines how this should be done by defining a container system analagous to a set of folders in your file system.

The standard defines that there must be a file called 'mimetype' at the root level of the container and the mimetype file should comprise the ASCII string: "application/epub+zip". By so doing, reader software can confirm that the file it's been asked to open with extension .epub is intended to be an epub publication. There may be other problems that make it invalid, but the mimetype file is an assertion that the container and its contents should be handled as an epub document.

To further qualify as valid epub, the container file system must include a folder called 'META-INF' and that folder must contain a file called 'container.xml'. It may contain other files, which will be the subject of later posts in the blog, but it must have container.xml.

Figure 2. shows the contents of our container.xml, again opened in Visual Web Developer 2008 Express Edition.

Figure 3. OCF Container

container.xml has a root node called <rootfiles>. In our example there is only one <rootfile> and that points to the package file: 'OPS/ebp.opf'.

The standards working together
We've seen that our sample epub, The Curious Case of Benjamin Button, has satisfied the requirements of the Open Container Format - it has a valid mimetype file and a META-INF folder with a valid container.xml.

Reading software accessing the epub will open container.xml and use it to locate and open the Open Package Format information in the indicated .opf file. Typically, the Table of Contents will be opened and displayed and the first content document will be displayed in a viewing area.

The vocabulary of the content documents should hold no surprises for the reading software and it should be able to render the text with the structure and style indicated, including the display of any referenced images.

In this simple example, that is how the different IDPF standards work together. In subsequent posts we'll look at these features in greater detail, show how their scope is wider than I've shown so far, and also start looking at C# Class modelling of epub entities.

First look inside an epub ebook

2010-01-01T10:19:00.043Z

In this article we will download an ebook from the web and examine its structure using common browsing tools. For this exercise you will need to be able to view the contents of Zip files and to display XML files.

I have a fully paid for and licenced copy of WinZip, so that's what I'll be using in the instructions and screenshots. If you haven't, there are many ways of opening Zip files - take a look at How to open a Zip file without WinZip for some examples.

For browsing XML documents I use Internet Explorer and Visual Web Developer Express Edition from Microsoft. If you don't use Internet Explorer, most other browsers will also display them; or take a look at Viewing XML Files at W3Schools.

The purpose of this exercise is to get our hands dirty on a real ebook without looking too closely at the standards documents referred to in the Introduction to epub post.

Download an ebook in the epub format
Go to the epubBooks website and download the free ebook: The Curious Case of Benjamin Button. This is a short story by F.Scott Fitzgerald and, as an ebook, has a fairly simple structure. This makes it suitable for illustration of some key ideas about how epub books are put together. For convenience, save the download to a new folder.

Figure 1. Downloaded epub ebook

(Hint: click on thumbnails to see the full screenshot or image)

Figure 1. shows how the saved ebook looks on my machine. Notice that the ebook download consists of a single file with the file extension .epub.

Open the ebook using your Zip file viewer

We'll look at the Open Publication Structure shortly but for now open the file using WinZip, or whichever program you are using to view Zip files. Figure 2. shows the contents of the file when the folder view of WinZip is switched on.

Figure 2. epub document opened in WinZip

Figure 2. demonstrates first of all that the epub format uses Zip compression technology to package the different parts of an ebook into a single file. Next, notice that, at the top level of the folder hierarchy, there is a file called 'mimetype' and there are two folders called 'META-INF' and 'OPS'. The OPS folder has two sub-folders called 'css' and 'images'.

Figure 3. shows the full contents of the file when the folder view is switched off. This view is sorted by the Path column.

Figure 3. Alternate view of the book contents

In this view, you can see that the META-INF folder holds a file called 'container.xml'. This file holds information that conforms with the Open Container Format. We'll look at what that means shortly.

The OPS folder contains a set of files with names like 'chapter-nnn.xml'. You might guess correctly that these files hold the text of each chapter of the book in XML format. There are a few other files with the .xml extension: 'title.xml' and 'epubbooksinfo.xml'. These are also parts of the book that will be displayed when you read it, namely its title page and a page of information about epubBooks.

Also in the OPS folder are two important files: 'epb.opf' and 'epb.ncx'. These files contain metadata or 'data about data' and together they describe the content of the book and things like the order in which the content files should be displayed by the reading device. A file with extension .opf is used to identify information that conforms with the Open Package Format, and a file with extension .ncx identifies a document containing navigation information i.e. the reading order of the content files.

The folder called 'css' contains the files that apply some initial styling to the document. Aspects like relative font-size, text decoration (underline etc.), and margins are included, but it's common for the reading device to leave to the reader the choice of such aspects as font, font size. and text and background colours.

Folder 'images' contains the images that are displayed in the book. In our example the images folder holds only a logo for epubBooks which is displayed on the 'epubbooksinfo' page.

So far, you've seen words like Container and Package without getting any detailed explanation of what they mean. Nor have you seen any reference to Open Publication Structure. That has been deliberate. Each of these concepts will be the subject of separate posts, indeed each topic will span several posts as we relate what we see in the example epub document both to the OPS specifications and to the development of a class model in C# which we can use to read and manipulate epub documents.

Desperate to read Benjamin Button?

By the way, if you're absolutely desperate to view the book before we examine it technically, you will need an epub reading device. That means any combination of hardware and software that allows you to open and display an epub document. This could be a smartphone, a dedicated reader, or your PC. On your PC you could download and try Adobe Digital Editions which allows you to hold and view a library of ebooks.

Introduction to epub

2009-12-31T17:40:00.005Z

In this series of articles I intend to explore the structure of ebooks held in the epub document format as defined by the International Digital Publishing Forum. This will include developing an understanding of the different components of epub as defined by the following standards documents: Open Publication Structure, Open Packaging Format, and Open Container Format. If you take a look at the standards you will see that, like so many documents of their type, they are formal, dry, and require further explanation - and that is what I aim to provide.

I will also create a set of C# Classes to model the different components of epub and use them to develop a range of ASP.Net samples which will illustrate the unpacking and display of an epub document.

It's in the nature of epub that it uses Zip technology to compress and package all components of a publication into a single file, normally with the .epub extension. The code samples will use a freeware tool for handling Zip files. Further, the subdivisions of an ebook into Parts, Chapters, and Sections is typically handled using XHTML documents. To work with XHTML, the examples use the easily available Tiny MCE package to display ebook contents.

If you want to run these samples on your own machine, you will need to download these tools. I'll give URLs for download at the appropriate places.

In the next article we will start by downloading a free ebook and taking a look inside it.

Copyright © Colin Hazlehurst, 2009