doc.transformers.se_tpb_dtbookfix.html Maven / Gradle / Ivy
se_tpb_dtbookFix
se_tpb_dtbookFix
Transformer Purpose
This Transformer will manipulate a DTBook document, attempting to fix common invalidity errors ("repair") and/or
modify the document structure to improve the quality/appearance even if the input document is valid ("tidy").
The Transformer uses XSLT as the preferred executor type. Read further in Development Guide below.
Input Requirements
A wellformed DTBook document. If the existing executors do not support the version of the input document, they are automatically disabled.
Output
On success
A DTBook document of the same version as the input DTBook document, with
zero or several changes made to the document structure. No guarantees are made that an invalid input
will be repaired to a valid state.
On error
On execution error, the transformer will throw an exception and abort.
The transformer will not throw an exception on failure to repair an invalid input document to a valid state. (Validation is done inline to DEBUG, and by the script on final result, so messages will be conveyed regarding repair success.
Configuration/Customization
Parameters (tdf)
See ../../transformers/se_tpb_dtbookFix/transformer.tdf
Development Guide
The following section describes principles to take into account when adding a new Executor (XSLT or Java class) to this Transformer.
- Executor
Any document manipulation routine bundled in this Transformer must be an
extension of the abstract class Executor.
- Categories
Executors are grouped in categories. At the time of writing,
three categories (REPAIR, TIDY and the internal NARRATOR) exist, but more can be added should the need arise.
- Executor Granularity
Fix/Tidy functionality authors are encouraged to add *one* fix/tidy feature
per executor to allow finely-grained sorting/filtering.
- Extensibility
-
The Transformer is written to allow swift addition of new repair/tidy functionality.
To allow multiple context use, the preferred Executor technology is XSLT,
but the Transformer allows associating other executors
(such as javaclasses) with a category.
Besides appending new Executors, additional categories can be added as well.
- Input version handling
-
An Executor implementation must never change the DTBook DOCTYPE/version between input and output.
Before calling any Executor, the Transformer main class will assure that the prerequisite is met that
there exists no ambiguity in the documents stated DOCTYPE/version. In other words, an Executor implementor
can use any token (DOCTYPE, dtbook@version or the DTBookVersion parameter) to determine input version.
By extending the abstract Executor class, you are by contract forced to implement the supportsVersion
method. Any Executor that returns false on the call to this method will be removed from the Executor list before launch.
Every such disabling will yield a warning message to the Pipeline EventBus.
- Prerequisites
-
The main Transformer class will assure that the following prerequisites hold true before
launching the Executor list(s).
- Proper root namespace declaration, making the DTBook namespace the default namespace
(does not guarantee that the xmlns attribute is not DTD defaulted)
- No DOCTYPE/version ambiguity
If these prerequisites are not met, a TransformerRunException is thrown.
- Reporting when modifications are done
-
Executor implementors are recommended to report when actual modifications
are made. The way to do this depends on the executor type:
- XSLT executors report through
xsl:message.
- Java executors report through any means available to reach the EventBus
(either via direct call, or through the
TransformerDelegateListener interface.
- XSLT integration
XSLT stylesheets are typically placed in the /xslt/subdirectory of the transformer
main directory, and then integrated into a Category by adding a one-liner to the
DTBookFix#createCategory method, which
will create an instance of the XSLTExecutor convenience class.
Further development
New repair and tidy Executors are added as real-world error patterns reveal that they are needed.
Dependencies
An XSLT 1.0 and 2.0 processor
Author
Joel Håkansson, James Pritchett, Linus Ericson, Markus Gylling
Licensing
LGPL