doc.developer.tdf-grammar-v1.1.html Maven / Gradle / Ivy
Transformer Description File (TDF) Grammar version 1.1
Daisy Pipeline Transformer Description File (TDF) Grammar version 1.1
Latest update: 2007-03-27
This documents describes the Transformer Description File grammar for the Daisy Pipeline.
Contents
The grammar
The Transformer Description file (TDF) is divided into three main parts, the general information part, the parameters part and the platforms part.
General information
The general information part of the TDF contains a set of elements:
- name
- The (nice) name of the transformer.
- description
- A brief description of what the transformer does.
- classname
- The name of the Java class for this transformer. The classname should be the fully qualified classname
starting from the
transformers directory.
- license
- The license of the transformer (e.g. LGPL).
- author
- The author of the transformer.
- support
- Explains if there is any (user) support available for this transformer.
- documentation
- The uri attribute contains a relative link to extended documentation of the transformer.
Normally, the destination of the URI is an XHTML document in the
/doc/transformers subfolder.
A template for this XHTML document exists in the /doc/templates folder.
Parameters
The parameters element contains a set of parameter elements. A parameter can be
configured to be supplied from the task script when the transformer is run, or be hard-coded in the Transformer Description File.
During execution time, these parameters will be supplied to the Transformer as a Map in the execute() method.
The Transformer accesses each parameter by the name defined in the TDF.
For hard-coded parameters, three values needs to be specified: A type attribute specifying the MIME2 type
of the parameter, a name element specifying the name of the parameter and a value element specifying the value.
For parameters that are to be supplied by the task script, things are a bit more complicated. First, there is a required attribute specifying whether
the parameter must (or just may) be supplied in the task script or if it can have a default value. If the value of the required attribute is
false, there must be a default element in the end of the parameter element specifying the default value.
As there was for hard-coded parameters, there is also a type attribute specifying the MIME2 type of the parameter.
There may also be a direction attribute having the value in or out. Input parameters
(e.g. input file name) should have the direction="in" attribute, and output parameters (e.g. output file name) should have the
direction="out" attribute.
To create parameters with enumerated values, the type parameter shall be set to 'enum'. After the example element, an enum
element must be defined having the following syntax:
<enum>
<value>ONE</value>
<value>TWO</value>
<value>THREE</value>
</enum>
The parameter element has three sub elements, the name,
description and example elements, specifying the name
of the parameter, a description of what the parameter does (for documentation
purposes or for use as balloon help in GUIs) and an example value. As described
above, the default element must only be specified when the
required attribute is set to false.
Variable substitution
A fixed set of variables are usable in the parameter definitions which are substituted dynamically when the TDF is parsed:
${transformer_dir}: The path to the directory containing this TDF${dollar}: A dollar sign
Parameter examples
In the example below, the required input parameter ncc should be of type
application/x-ncc-2.02+xml.
<parameter required="true" direction="in" type="application/x-ncc-2.02+xml">
<name>ncc</name>
<description>The navigation control center file</description>
<example>file:///path/to/ncc.html</example>
</parameter>
In the example below, the value will be substituted to the path of the style sheet located in
the same directory as the TDF.
<parameter type="string">
<name>stylesheet</name>
<value>${transformer_dir}/xml2dtbook.xsl</value>
</parameter>
Platforms
The platforms element contains a set of platform
elements. If specified, the current platform must match at least one of the
platform elements in order for this transformer to be considered
as supported.
Each platform element contains a set of property
elements. Each property checks a specific platform property and all property
checks within a platform element must be successful in order to
qualify as a supported platform.
Each property contains a name element and a
value element. The name element specifies the name
of the property to check, and the value element contains a
regular expression describing the supported values of that property. The
properties and their values are defined in the java runtime system. In the
example below, Windows systems of version 5 and any Linux system are supported:
<platforms>
<platform>
<property>
<name>os.name</name>
<value>Windows.*</value>
</property>
<property>
<name>os.version</name>
<value>5\..*</value>
</property>
</platform>
<platform>
<property>
<name>os.name</name>
<value>Linux.*</value>
</property>
</platform>
</platforms>
Example
<transformer version="1.1">
<name>Validator</name>
<description>Validate filesets and XML documents of various types</description>
<classname>int_daisy_validator.ValidatorDriver</classname>
<license>LGPL</license>
<author>Markus Gylling</author>
<support>https://lists.sourceforge.net/lists/listinfo/daisymfc-support</support>
<documentation uri="../../doc/transformers/int_daisy_validator.html"/>
<parameters>
<parameter required="true" direction="in" type="application/xml">
<name>input</name>
<description>Path to input file or fileset manifest to be validated</description>
<example>C:/myDocuments/myDocument.opf</example>
</parameter>
<parameter required="false" type="enum">
<name>requireInputType</name>
<description>A string describing one input type that is required,
else an error will be generated. (These are from
FilesetType.getNiceName)</description>
<example>Dtbook</example>
<enum>
<value>off</value>
<value>Dtbook document</value>
<value>XHTML document</value>
<value>DAISY 2.02 DTB</value>
<value>Z3986 DTB</value>
</enum>
<default>off</default>
</parameter>
<parameter required="false" type="string">
<name>schemas</name>
<description>
Comma separated list of schema identifiers to validate the input document against.
Identifiers may be expressed as filepaths, public or system IDs.
RelaxNG, W3C Schema, Schematron and Compound are allowed types of schemas.
Schemas that occur inline in the validated document do not need to be namedropped here.
</description>
<example>
D:/example.sch, http://www.example.com/example.rng, -//TPB//RNG dtbook 2005-1 Narrator//EN</example>
<default/>
</parameter>
<parameter required="false" type="string">
<name>delegates</name>
<description>
Comma separated list of delegates (implementations of org.daisy.util.fileset.validation.ValidatorDelegate)
</description>
<example>org.daisy.util.fileset.validation.delegate.impl.XMLEncodingDelegate</example>
<default/>
</parameter>
<parameter required="false" type="string">
<name>forceImplementation</name>
<description>
A fully qualified name of an implementation of a org.daisy.util.fileset.validation.Validator.
Use this parameter to force the validator to use the named implementation (overriding default assignment)
</description>
<example>org.daisy.util.fileset.validation.myValidatorImpl</example>
<default/>
</parameter>
<parameter required="false" type="enum">
<name>abortThreshold</name>
<description>Validation error severity level - when to perform a Transformer abort</description>
<example>WARNING</example>
<enum>
<value>NONE</value> <!-- dont abort on any kind of validation message -->
<value>WARNING</value>
<value>ERROR</value>
<value>SEVERE</value>
</enum>
<default>ERROR</default>
</parameter>
<parameter required="false" type="enum">
<name>abortOnException</name>
<description>Whether to perform a Transformer abort when a caught exception occurs</description>
<example>false</example>
<enum>
<value>true</value>
<value>false</value>
</enum>
<default>true</default>
</parameter>
<parameter required="false" direction="out" type="application/xml">
<name>xmlReport</name>
<description>Path to xml output</description>
<example>/home/user/reports/myreport.xml</example>
<default/>
</parameter>
<parameter required="false" type="string">
<name>xmlStylesheet</name>
<description>
The value of the xml-stylesheet processing instruction in the
generated xml output. If absent, no xml-stylesheet will be inserted
in the output. Only looked at if xmlReport is not null.
</description>
<example>validator.xsl</example>
<default/>
</parameter>
</parameters>
</transformer>
Notes
2. The Pipeline uses more MIME types than those defined by IANA.
The Pipeline MIME registry (MIMETypeRegistry.xml) lives in the org.daisy.util.mime. package.
If you do not have access to the source code,
browse the registry online.
Appendix. RelaxNG+Schematron grammar for tdf v1.1
<?xml version="1.0" encoding="UTF-8"?>
<grammar
xmlns="http://relaxng.org/ns/structure/1.0"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
>
<!-- RelaxNG schema for Transformer Description Files (*.tdf) -->
<!-- v1.1: added the optional documentation element -->
<start>
<ref name="transformer"/>
</start>
<define name="transformer">
<element name="transformer">
<attribute name="version">
<data type="normalizedString"/>
</attribute>
<ref name="details"/>
<ref name="parameters"/>
<ref name="platforms"/>
</element>
</define>
<define name="details">
<element name="name"><text/></element>
<element name="description"><text/></element>
<element name="classname"><text/></element>
<zeroOrMore>
<element name="jar"><text/></element>
</zeroOrMore>
<element name="license"><text/></element>
<element name="author"><text/></element>
<element name="support"><text/></element>
<optional>
<element name="documentation">
<attribute name="uri">
<!-- the uri is relative to transformer TDF document,
and thus typically looks (../../doc/transformers/transformerdoc.html)
-->
<data type="anyURI"/>
</attribute>
<empty/>
</element>
</optional>
</define>
<define name="parameters">
<element name="parameters">
<zeroOrMore>
<element name="parameter">
<choice>
<ref name="parameter_normal"/>
<ref name="parameter_hard"/>
</choice>
</element>
</zeroOrMore>
</element>
</define>
<define name="platforms">
<optional>
<element name="platforms">
<oneOrMore>
<element name="platform">
<oneOrMore>
<element name="property">
<element name="name"><text/></element>
<element name="value"><text/></element>
</element>
</oneOrMore>
</element>
</oneOrMore>
</element>
</optional>
</define>
<define name="parameter_normal">
<sch:pattern name="Required attribute test"
xmlns:sch="http://www.ascc.net/xml/schematron">
<sch:rule context="transformer/parameters/parameter">
<sch:report test="@required='false' and not(default)">
A non-required parameter must have a default value</sch:report>
</sch:rule>
</sch:pattern>
<sch:pattern name="Enum test" xmlns:sch="http://www.ascc.net/xml/schematron">
<sch:rule context="transformer/parameters/parameter">
<sch:report test="@type='enum' and not(enum)">
Enum type must be defined</sch:report>
<sch:report test="enum and not(@type='enum')">
Type is not enum</sch:report>
<sch:report test="enum and default and not(default=enum/value)">
Default value must be of enum type</sch:report>
</sch:rule>
</sch:pattern>
<attribute name="required">
<data type="boolean"/>
</attribute>
<attribute name="type">
<data type="normalizedString"/>
</attribute>
<optional>
<attribute name="direction">
<choice>
<value>in</value>
<value>out</value>
</choice>
</attribute>
</optional>
<element name="name"><text/></element>
<element name="description"><text/></element>
<element name="example"><text/></element>
<optional>
<element name="enum">
<oneOrMore>
<element name="value"><text/></element>
</oneOrMore>
</element>
</optional>
<optional>
<element name="default"><text/></element>
</optional>
</define>
<define name="parameter_hard">
<attribute name="type">
<data type="normalizedString"/>
</attribute>
<element name="name"><text/></element>
<element name="value"><text/></element>
</define>
</grammar>