Tag Archives: technical writing

Adding a table of contents to your ePUB

With ePUBs it is straightforward to add a table of contents to your book, allowing your readers to quickly navigate within your content. Interestingly how you do it is not a part of the ePUB specification itself, but highlights ePUB’s development from earlier digital book initiatives.

This article assumes you are creating/editing your ePUB source content directly. If generating an ePUB via a development tool (eg Pages, InDesign) then it can automatically generate the TOC for you. However even if doing so this article will help describe what is being built for you.

To help, I’ve included a smorgasbord of sample ePUBs to demonstrate how tables of contents are included. There’s a basic book (single level/standard TOC) as well as books with 2, 3, 4, or 5 level TOCs.
Download the one you want or take the whole pack. Note that because WordPress considers EPUBs a security risk, they’ve all be zipped.

Do I need to do this?

A table of contents is optional (your ePUB is valid and usable without one). What’s more how it actually presents for your readers is dependent on the reader. As such you should decide for each book, and your target market, whether worth the development effort.

How do I do this?

Adding a table of contents to your ePUB has two key steps:

  1. Creating a valid .NCX file
  2. Including the .NCX file in your book

Let’s work through these steps in turn.

Creating a valid .NCX file

The .NCX file defines your table of contents. There’s no rule about what filename to give it, but the default option for most eBooks appears to be TOC.NCX. So we’ll assume we’ve called it that too.

The definition for your TOC.NCX file is not part of the ePUB specification but is instead maintained by the DAISY Consortium and co-opted by IPDF who manage ePUBs for us. Browse the detailed specification and see if you can find out what NCX stands for.

In essence an .NCX file is an XML file. It lists the elements for your table of contents within a simple and standard framework:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ncx
  PUBLIC "-//NISO//DTD ncx 2005-1//EN" 
  "http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
<head>
	-- insert required metadata
</head>
<docTitle><text>DOCTITLE</text></docTitle>
<docAuthor><text>DOCAUTHOR</text></docAuthor>
<navMap>
	-- insert required navigation structure
</navMap>
</ncx>

Copy that and use as the basis for your TOC.NCX, while we fill in the missing bits: metadata, title, author, navigation structure.

(1) insert required metadata

Every .NCX file needs to define four metadata elements:

  • dtb:uid – this is the unique ID for your publication.  It needs to match the ID given in content.opf.
  • dtb:depth – this is the number of levels in your TOC. Normally this would be 1 but you can add more levels – see hierarchical contents below
  • dtb:totalPageCount – this is not used: set to zero
  • dtb:maxPageNumber – this is not used: set to zero

For example, here’s the .NCX header for a standard table of contents with only 1 layer of entries.

<head>
	<meta name="dtb:uid" content="a897sad23fd23ds" />
	<meta name="dtb:depth" content="1" />
	<meta name="dtb:totalPageCount" content="0" />
	<meta name="dtb:maxPageNumber" content="0" />
</head>

 

(2) record title and author

The document title and author should match those recorded in the main metadata within content.opf (DC:Title, DC:Creator respectively). Some readers may reference these values when displaying the contents, although those in my limited test suite all seem to ignore these values and focus on those in content.opf.

In the sample ePUBs included with this article I deliberate added “(NCX)” to the end of the title and author in each .NCX file. Just to see if/where it appeared. Never did. But your mileage may vary.

(3) insert required navigation structure

The navMap is where the entries in your table of contents are defined using special XML elements called navPoints.

<navPoint playOrder="x">
     <navLabel>Text to show in the table</navLabel>
     <content src="url" />
</navPoint>

The playOrder is numeric, indicating the sequence that the content elements should be traversed in when navigating.  Note that this does not need to match the order you list them (and they appear) in the TOC. Nor does it need to match the sequence in the <spine> section of content.opf.

My testing (and the OPF specification) indicate that the playOrder is not used to determine the sequence content is browsed. When users move through the content sequentially, this sequence is defined by the <spine> element in content.opf. However, even though playOrder is not used, it is recommended that meaningful values are recorded “just-in-case”. It also ensures your ePUB validation, if using epubcheck, will be successful.

The text will present as entered in your TOC; be mindful that not all readers will have a lot of room so don’t make the entries too long.

The URL needs to be the reference to the file/location that is the target of this TOC entry. This will be the filename if you have created separate chapter files. Else you could reference separate sections within a single document via anchor tags.

For example, here are sample entries from the start of one EBook.


<navPoint playOrder="1">
  <navLabel><text>cover</text></navLabel>
  <content src="00-cover.xhtml" />
</navPoint>
<navPoint playOrder="2">
  <navLabel><text>preface</text></navLabel>
  <content src="10-frontis.xhtml#preface" />
</navPoint>
<navPoint playOrder="3">
  <navLabel><text>credits</text></navLabel>
  <content src="10-frontis.xhtml#credits" />
</navPoint>
<navPoint playOrder="4">
  <navLabel><text>Chapter 1 - Background</text></navLabel>
  <content src="chapter1.xhtml" />
</navPoint>

Note: If using anchor tabs, the other end of the link needs to be to an ID, not name tag. Read this for the explanation.

Including the .NCX file in your book

Only two small changes are made to your existing eBook to include your .NCX content, both made to content.opf:

  • add your TOC.NCX file to the ebook manifest. Application type needs to be
    application/x-dtbncx+xml
  • add a reference to the new TOC.NCX to your ebook spine. This is added as an attribute in your <spine> tag:
<manifest>
  <item href="toc.ncx" id="ncx" media-type="application/x-dtbncx+xml"/>
  ...
</manifest>

<spine toc="ncx">
  <itemref idref="chapter1" />
  ...
</spine>

That’s it. Save CONTENT.OPF, build and test.

Next steps

Once you’ve mastered the basic table of contents, you’re ready to investigate some more advanced options:

hierarchical contents

You can create multiple levels in your table of contents simply by nesting your navPoint elements.

...
<navPoint id="navpoint" playOrder="1">
          <navLabel>Chapter 1
          <navPoint playOrder="2">Section 1</navPoint>
          <navPoint playOrder="3">Section 2</navPoint>
...

Don’t forget to work through the playOrder values to retain a logical sequence to your content. Even though not sure who/where these values are used :-)

How hierachical contents are displayed or navigated depends very much on the reader. It also appears to vary how many levels of content are supported. The standard itself sets no limits (or tells you what to call them: chapter, part, section, ..). However mileage may vary with different readers so don’t go overboard. The following table shows results with the two readers I spend most of my time with: Adobe Digital Editions (ADE) and iBooks (on the iPad). The two columns for ADE show the default view (when first opening your book) and the expanded view.

single level (basic book)
two levels
three levels
four levels
five levels

Notice:

  • for iBooks, it gives up after 2 levels of contents. Unable to find anything official that states that’s a limit, but if aiming for that platform I’d stop at 2.
  • for Adobe Digital Editions, the menu gets a little confused at the deeper levels – notice at 5 levels of contents the first level does not appear. Not sure if anything can be done to fix that, but also reason to avoid going that deep.

The above images are taken from the sample ebooks included with this article. Feel free to use to test how well supported in your chosen reader.

multiple tables (pageLists and navLists)

The standard table of contents is defined within a navMap. This is the complete, logical structure of your book. However the .NCX specification also allows you add two additional types of references to your TOC:

  • pageList – use if needing to offer navigation by page (rather than topic/section). Your ePUB can only include one pageList, and it cannot be hierarchical – one layer only.
  • navList – use if wanting to offer other any other arbitrary collection of topics, for example a list of illustrations or a collection of chocolate recipes taken from your complete recipe book. You can have as many navLists as you want, although they too can only be single level. An additional element, navLabel, can be added to give a title to your collection.

The steps involved in defining and including these tables is complex enough to warrant their own article, coming soon.

Conclusion

A table of contents is a valuable addition to most books, particularly non-fiction or reference titles. Adding one is reasonably simple, and thus worth the effort. However keep to the basics if wanting to be functional in the widest range of readers.

Building and publishing an eBook on your iPad

When you start researching online how to publish an eBook, the focus is strongly on commercial release to the general public.

However, particularly in the corporate world, you may not want to make your book publically available. So how do you get all the benefits of an eBook on the iPad (and/or the excuse to buy an iPad for business use) but without releasing your internal documents to the world? After some research, trial and error, the process is really quite simple.

To have your very own library on your very own iPad just three steps are required:

  1. create a valid eBook
  2. drag that book into iTunes, and
  3. synchronise your iPad with your updated iTunes library.

Your personal eBook will then be available on your iPad, right there alongside, and indistinguishable in quality, your John Grisham collection. Or your Alice in Wonderland collection if still stuck in a region – like here in Australia – with no functioning iBooks store.

Step 1. Create a valid eBook

While this may appear daunting it’s really straightforward once you realise a few simple truths.

  • iBooks supports eBooks produced in the standard ePub format (read more on Wikipedia)
  • an ePub book is simple a zipped folder with a different extension (changes .zip to .epub)
  • within your eBook your content must be included as XHTML files, one file per chapter
  • accompanying your content are a variety of XML files that define the structure and order of your content

Sample ePub contents - just XHTML and XML files
And that’s it. You don’t need anything more complicated than a text editor and a folder zipping tool. It’s so simple I strongly recommend you (at least the first time) build one manually. It’ll give you a much better understanding of how it all comes together, and what options you have in defining and manipulating your content.

There are several tutorials online to help guide you through the process to build an eBook.  I recommend you follow this one from jedisaber. Download the sample file provided and follow the steps.

If your experience is the same as mine, most of the issues you’ll face when generating your first book will be in producing valid XHTML content. As such it’s recommended you build and validate this first. Issues I had included:

  • incorrect nesting of tags
  • not closing tags (particularly the img and br items)
  • missing attributes (particularly alt on all my images)

However use a decent XHTML validator (if not using Safari – which tests automagically – go for the master and use the one from W3C) and you’ll get through them.

Outside the XHTML the only other issue was in ensuring all the content files were encoded correctly:

Set encoding in BBEdit (OSX)
On the Mac I was using BBEdit. It gives you an option in the Edit Window to set the encoding: pick UTF-8. Note I also picked Windows CRLF because I was using a PC to package the book, more on that later.

Set encoding in Notepad (Win7)
On the PC I was using Notepad to edit. It allows you to set the encoding when saving. Again, choose UTF-8.

 
Once all your content is complete and valid, you can then compile your book in the folder you’ll then zip and rename to become the finished ePub. Follow the instructions (and sample) from jedisaber:

  1. ignore mimetype and META-INF (content does not need to change from one book to the next)
  2. load your valid content into OPS folder, documents and images (use subdirectory for your images if you set the URLs in your content to match)
  3. edit content.opf (XML file) to list all your content (and only your content – remove references to sample files not used). Make sure the URLs are correct, particularly if using subdirectories in OPS to organise your content
  4. edit toc.ncx (XML file) to list your content in the order to be navigated and with the section/chapter titles as you want them to be shown
  5. ZIP the folder
  6. Rename the folder from a .ZIP extension to a .ePUB extension

Be careful generating the ZIP version on a Mac using the built in compression tool. Not only does this incorporate all the hidden OSX files (DS_Store, etc) it also seems to put an extra folder layer in. I was only able to generate the correctly formatted ZIP file using Winzip on a PC.  This also allowed me to set the compression for the mimetype file to 0% as requested.

Note I managed to resolve the “extra folder” issue in OSX. Trick is not to choose your eBook folder to compress. Instead select the contents of that folder (should be three things: mimetype and META-INF and OEBPS folders) and compress them. You’ll get an Archive.Zip file you can then rename. This doesn’t resolve the potential issue with hidden files but I’ve not had any issues with ePUBs built this way since.

I then suggest you validate the eBook prior to the move into iTunes. Use the online threepress tool – it’s free. It may identify a few items you’ll need to return to your source to resolve. Just make the edits, rebuild/rename the ZIP and try again.

With that tool the only error I was not able to get rid of concerned the length of the first filename. I’m guessing this is because the requirement is for mimetype to be the first file in the ZIP file but I could not find any way to enforce this. However even with this error I did not get any issues with the subsequent steps so if you get this error, ignore it like I did.

If the book validates, then also consider testing it in a reader outside of iTunes. I used the bookworm from O’Reilly. Alternatively try Adobe Digital Editions, a free download so you can test your books without a web connection.

Step 2. Drag into iTunes

Simply open iTunes, select your Books folder, and drag your .epub file into the window. If all works well you should see your book listed, with its cover appearing in all its glory.

Note you cannot open/view/test the book from here. That only happens when you get it onto the iPad.

Step 3. Synchronise and launch on your iPad

When you sync your iPad just ensure its set to include all new eBooks. Your file will then get copied across and be ready for use. Congratulations!

Next steps

Using XHTML it’s straightforward to include text and images in your content. So feel free to improve on your content’s richness. Also consider adding a stylesheet (include in your content.opf file, as well as referenced in your XHTML) to further enhance the presentation.

You can easily add a nicer title/cover page so your book looks better on the shelf. Either build in XHTML or just create as a nice image and include.

From this foundation, the next step for me is to see if possible to include some richer media in the book. For example a video or audio snippet. We’ll see how that goes….

Resources

Note: All the online tools listed here require you to upload your content to their servers. Be mindful of how secure you want/need your content to remain before using any of these tools.

iWorks Pages: Adding vertical column headings

Pages is a glorious tool for drafting documents, particularly if you’re sick of working on documents from people who think every possible style permutation is acceptable and to be added by editing font sizes and layouts directly.

However every now and then you find missing a feature you take for granted in the opposition.  One of those is vertically aligned column headings.

To add such headings in Pages:

  1. Generate your table to get an approximate size for your heading cell.
  2. Create a textbox the same size as the heading cell. Use the Metrics inspector to help size the box and change the rotation to 90 degrees (to read bottom to top) or 270 degrees (to read top to bottom)
  3. Enter the required text – note it will flip back to horizontal while you type.
  4. Apply the required styles and alignment so you’ve an accurate picture of how large it needs to be.- Check the wrap inspector to ensure the text box does not cause wrapping
  5. Drag the text box over the top of the column heading it is to provide
  6. Do some final edits to coordinate the size of the text box and the column.

And that’s it.

If needing to add vertical headings to multiple columns it’s easier to duplicate the first one (click Option-Drag) and edit, rather than creating several from afresh.

Information Mapping™ in a nutshell

Information Mapping™ is a formal methodology for writing usable documents. It provides techniques to analyse, organise and present information to maximise its effectiveness.

The methodology was initially developed in the 1960s in the US. It is often described as research-based since all its techniques and principles are derived from research in human factors, cognitive science, etc.

The methodology is owned by Information Mapping Inc, based in Waltham Massachusetts. Partnerships are established worldwide to provide Information Mapping training and support in other countries.

methodology in a nutshell…

Information Mapping™ provides a simple three-stage process for creating documents: analyse, organise, present.

For analysis:

  • Information Mapping™ identifies all information as one of a limited series of types (eg process vs procedure vs principle, etc).
  • The key activity when analysing information is determining its type.

For organisation:

  • Information Mapping™ provides a series of principles on how to organise your information types.
  • Key to the principles is:
    • breaking information into discrete, bite-sized chunks (called blocks) on a single topic
    • limiting the number of blocks in a topic (called a map, hence the name of the methodology) to 7±2. This magical number is the theoretical limit of human short-term memory. Organising information around this limit helps users comprehend the content without feeling overwhelmed.

For presentation:

  • Information Mapping™ provides recommendations of the most effective formats for presenting each of the information types
  • Additionally it provides principles to help ensure the document is easy to scan/speed-read.

The methodology introduces two new organisational units for documents:

  • block – a single unit of information (= one information type) on a single subject. Can contain text, tables, images, etc. To be “blocked” it needs to be visually distinct from other blocks (the presentation standard is a line above/below) and with a label that describes its content.
  • map – a collection of blocks (7±2 ideally) on a single topic. It contains all the blocks on the given topic as well as an any introduction/conclusion block(s) required.

Above the map, mapped documents are organised into sections, then parts. Key at all levels is adherence to the 7±2 limit (eg a section should not have more than 9 maps, a part no more than 9 sections, etc).

what are the advantages?

There are three real advantages for organisations in adopting Information Mapping™:

  • improvement in document quality
  • upskilling/appraisal of new writers
  • standarisation of large writing teams

quality

A great deal of research has been conducted to quantify performance benefits when adopting IM. While your own figures may differ from the scientists there is no doubt that a well written IM document is easier use, particularly for reference (easy to scan, easy to find specific content, easy to understand that content when found).

upskilling

Information Mapping provides a framework that crystallises a great number of principles and techniques that good writers use anyway. It is therefore an excellent tool for:

  • raising the level of new writers
  • ensuring an acceptable rate of output for new users (no more writer’s block)
  • providing an assessment framework for helping good writers explain the issues with bad writing (without it getting too subjective/personal)

standardisation

Since the methodology is definitive in its principles, it is invaluable when trying to ensure a consistent and standard output across multiple writers. When well written, mapped content can easily be assigned/re-assigned between writers with everyone “understanding” exactly what each topic is to contain and how to provide it.

By adopting the methodology, organisations are also able to draw upon existing mapping trained writers to augment their in-house development teams. Eg if you need 5 manuals written, and only have resources for 2 of them you can outsource the others confident that the format/style will be consistent for all.

what are the disadvantages?

There are no real disadvantages, just two issues it is best to be aware of before committing to it.

  • paper-centric
  • presentation-obsessed

paper-centric

Traditionally (i.e. it predates the internet) Information Mapping™ is a paper-based approach. Now all of the techniques and principles are equally applicable online, but it does take some flexibility/creativity to make best use of the online format and adhere to the presentation guidelines.

To this end it is recommended you spend the time to review/define a formal mapping template for any online document before your writing team get too far into its development.

presentation-obsessed

Information Mapping Inc. say it all the time, and I agree with them: simply using the mapping template does not a mapped document make. The presentation is the tip of the iceberg (in workshops they used to say presentation was maybe 20% of the method’s power).

The recommended presentation is the optimum based on the research, but you are free to manipulate to better fit your own needs.

On most Information Mapping™ workshops, participants are provided a template and formatting tool (called Formatting Solutions) that facilitates development of IM-formatted documents. This is a series of MS Word templates/macros to speed up the production of IM documents. If skilled (or willing to pay) these templates can be customised for your own needs.

what are the alternatives?

A large number of training companies offer technical writing courses. And most of them will include principles similar to those in Information Mapping™. However IM probably rules the roost in terms of research-basis and consistency.

The only other method that probably came close to the rigour of Information Mapping™ was “Read-to-Do”. However we’ve been unable to find any recent references to this alternative, so perhaps it has fallen by the wayside.

how do I learn Information Mapping™?

You can only learn the method by attending a formal workshop organised by Information Mapping Inc or one of its partners. Depending on your location a series of workshops are available for different writing needs (eg writing memos vs writing technical handbooks).

All partners offer the workshops as public or in-house. In-house workshops are good if able to train your entire team, particularly if you can spend the time up-front to help customise the course content/templates (eg use your own materials during the exercises, etc).

how do I find out more?

The Information Mapping Inc website contains a lot of useful information and research on the methodology, including examples.

Alternatively contact your local partner (for Australasia it is TACTICS Consulting) who will be keen to provide any information you require.