Pipeline Script: DTBook Fix

Overview

This script will attempt to repair and tidy a suboptimal DTBook document. The script is primarily intended to address structural problems that occur in files that are output from automated conversion processes, such as the WordML to DTBook Script.

The actual manipulation routines performed are described in the DTBookFix Categories section below.

Input Requirements

A DTBook document. As is seldom the case in the Pipeline, the document need not be valid.

Note that the manipulations that are performed are heavily dependent on which version of DTBook is used (2005-1, 2005-2, etc). If your input document is of a version that is not supported by all or some of the manipulation routines that are performed, these routines will be disabled, and warnings will be issued.

Output

Depending on the input document version and your settings, the output document will have had anything from zero to several different structural modifications. Note that no guarantees are made that the output will be valid.

The input document is validated at the end of the process, so watch the validation messages that are issued towards the end of the process.

If you keep encountering DTBook documents with recurring problems that are not fixed by this Script, please contact the Pipeline development team.

Configuration

Input file
Required. Select input DTBook file
Output directory
Required. Select where to store the output result.
Active Categories
Select the type of manipulation to be performed by activating one or several Categories.
Read more on what is included in each category in the DTBookFix Categories section below.
Force Execution
Optional. When checked, DTBookFix will run all selected categories disregarding the input documents state (by default, the Repair category is run only if the document is invalid, and the Tidy category is run only of the document is valid).
Simplify heading layout
This is an optional routine within the Tidy category. Check the box to simplify the level structure by removing redundant levels.
See further Level cleanup below.
Tidy inline whitespace
This is an optional in Tidy category. Check box to move leading and trailing whitespace outside of em, strong, sub, sup, noteref and pagenum elements.
See further Tidy inline whitespace below.
Fix Character set
This is an optional routine within the Repair category. Check box to attempt to fix an invalid stated character set. See further Character Set recoder below.

DTBookFix Categories

This section gives a technical summary of the manipulations that are done within each DTBookFix manipulation category.

The Repair Category

Level splitter
Splits a level into several levels if a certain level1-6 element has several headings on the same level.
Level 1-6 repair
Inserts level1-6 elements where needed to meet the requirements on proper nesting
Illegal heading removal
Changes an illegal heading (for example, an h3 element inside a level2 element) into a p element. The p element will have the class attribute value of the original heading element name (e.g. <p class="h3">).
Flatten redundant nesting
Removes nested p
Complete structure
Adds an empty paragraph if the last element in the level is a heading
List repair
Character Set recoder
This will run a character set detection algorithm on the input file, disregarding any stated characterset, and then recode the entire file. Only enable this if you have explicit issues with character display, or when your document is reported to be malformed with stated reasons similar to "invalid byte sequence" or similar.
IDREF repair
Empty elements remover
Removes empty/whitespace elements that must have children.
Page number type repair

Changes the type attribute of the pagenum element to match the contents of the element (i.e. the page number value).

Incorrect "normal" page numbers will be changed to "front" if the contents contains roman numerals and the element is located in the frontmatter of the book. Incorrect "front" page numbers will be changed to "normal" if the contents contains arabic numbers. Otherwise the page attribute will be changed to "special" if it is incorrect.

Metadata repair

The Tidy Category

Level cleanup
Simplifies the level structure by removing redundant levels (subordinate levels will be moved upwards). Note that the headings of the affected levels will also change, which will alter the appearance of the layout.
Pagenum mover
Change inline pagenum to block
Removes otherwise empty p or li around pagenum (except p in td)
Empty elements remover
Removes empty/whitespace elements (p, em, strong, sub, sup), unless required for validity. E.g. an empty p that is preceded by a heading and followed only by other empty p is not removed.
Author and Title addition
Inserts docauthor and doctitle elements to frontmatter using Dublin Core metadata.
Tidy inline whitespace
Moves leading and trailing whitespace outside of em, strong, sub, sup and pagenum elements. For example: "this is an<em> example </em>of what<strong> Tidy inline whitespace </strong>does" will change to: "this is an <em>example</em> of what <strong>Tidy inline whitespace</strong> does". This is a requirement for accurate braille rendering.
Indenter
Performs a "pretty print" of the XML elements in the document.

Appendix: List of Transformers used

The documents linked below are parts of the Transformer technical documentation. These are developer and systems-administrator centric documents.

  1. se_tpb_dtbookFix