Duff (Daisy Utility For Formatting)

Duff is a tool designed to format Daisy digital talking books. A common use is to help printing of a Daisy book by making single file of its text content. Duff supports the Digital Talking Book version 2.02 specification, namely books with an XHTML Navigation Control Center (NCC), XHTML textual content and SMIL 1.0 multimedia content. This document covers the source distribution of the pre-release version 0.7 of Duff (17 Jul 2005.) Duff is free software and released under the GNU Lesser General Public License version 2.1.

Downloading Duff

The source release of version 0.7 is available from Sourceforge. Note about the project name: unfortunately, there is already a project named "Duff" hosted by Sourceforge, so the UNIX name for the project is fudd.

Compiling and Running Duff

Duff is implemented in Java, and should therefore run in any environment that supports Java (J2SE) version 1.4 or higher. Duff relies on two external libraries which must installed prior to compiling:

• Saxon (version 6.5.x); the file saxon.jar must be in your class path;
• the URI Resolver from the Apache xml-commons project (version 1.1); the file resolver.jar must be in your class path.

You can then compile Duff by the command javac Duff.java. If you wish to run Duff in Japanese or French, you also need to run the command perl to_ascii.pl which transforms the localization messages into the correct encoding for Java. You can then run Duff by calling the main class Duff.

Formatting a Daisy Book with Duff

There are currently three possible outputs for a given book:

1. Full book: this produces a single XHTML file resulting from the concatenation of the XHTML files containing the textual content of the book. This file can then be opened from an XHTML-aware application, such as a web browser, an HTML editor or a word processor, to be viewed, printed, or edited (depending on the application capabilities.)
2. Transcript: this produces a single XHTML file containing all the textual content that is explicitly associated with audio content. For instance, a book may contain pictures which are not described by the audio track; these will not appear in the transcript file (the exact output depends on how the was authored.)
3. XHTML TOC: in some cases, the concatenation of several HTML files will result into illegible content (one case may be the use of absolute position for elements such as images.) In this case, it is possible to create a table of contents (TOC) of the XHTML files in the book order. The result is an XHTML file with hyperlinks to the various files; they can they be easily accessed (but are still separate files that need to be viewed, printed or edited separately.)

Using the Graphical User Interface (GUI)

The GUI consists of a menu bar and an information window. Formatting a book with Duff is a two-step process. First, open the NCC file for the book (using the Open NCC file item of the File menu.) A file chooser will appear, in which you can select the ncc.html or NCC.HTML navigation control center file of a book. When a file was selected, a preliminary transformation is run to create an intermediary representation of the book that will be used by further transformations (the so-called XML table of contents of the book.)

Once the NCC file has been read, the Transform menu is enabled. From this menu you can either view the hierarchical table of contents of the book, or format the book. When you choose one of the three transformations described above, you will be presented with a file chooser where you can select the output file. At the moment, it is best to save the output in the same directory as the one where the XHTML files reside, so that links will stay consistent. Future versions will address this problem.

Menu reference. Following is a quick description of the menus of the GUI.

• File menu:
  • Open NCC file: open the NCC file of a Daisy book for processing.
  • Reload NCC file: once an NCC file was opened, it can be re-read in case any modification was made.
  • Print: this option is currently disabled. In the future, it will allow to produce PDF files directly from the application.
• Transform menu: this menu is enabled once an NCC file has been opened. From this menu, various transformations (i.e. formatting options) are available:
  • Show TOC: this option outputs the hierarchical table of contents of the book in the information view. This is useful for quickly viewing the contents of the currently opened book.
  • Full Book: make a single XHTML file for the book.
  • Transcript: make a single XHTML file for the transcript of the book.
  • XHTML TOC: build the XHTML table of contents with hyperlinks to the XHTML documents of this book.
• Skippable items menu: in this menu you can choose which optional contents you want to skip. Optional content is page numbers, sidebars, footnotes and production notes. You can decide to skip all of them, none of them, or skip some and not others. When an item is selected to be skipped, a check mark appear next to it in the menu. If there is no check mark, then the item is not skipped.
  • Skip all: skip all skippable items.
  • Skip none: skip none of the skippable items.
  • Skip page numbers: do not show the page numbers in the result document.
  • Skip sidebars: do not show the sidebars in the result document.
  • Skip footnotes: do not show the footnotes in the result document.
  • Skip producer notes: do not show the producer notes in the result document.

Implementation Details

Duff is specifically built on XSLT, the XML transformation language defined by the W3C. Since Daisy books are built out of XHTML and SMIL files, which are both XML formats, it is possible to transform a book stylesheets. The Java version of Duff uses the Saxon processor from Michael Kay.

The design of Duff is very simple. The core formatting functionalities are implemented with XSLT stylesheets, and the graphical user interface is implemented in Java. This design allows to cleanly separate the formatting functionalities, so that the same functionalities can be accessed from a different application: for example, a command line tool written in Perl can use the same stylesheets to make batch transformations faster than the Java version.

The application is also easy to customize by a user who knows XSLT. A future version of Duff will allow to easily add custome stylesheets for advanced formatting purposes. It is already possible in the current version to do so, but this necessitates to recompile the application.

Author

Julien Quint <pom@graougraou.com>, with support and funding from ELSA and NRCD.