8.8 Transform step

Transform step

Transforms input XML document or file using an XSLT 1.0 stylesheet. The result of the this step is the save file containing the transformed document.

Unlike the load step, if the input XML file starts with a <!DOCTYPE> pointing to a DTD, then the document loader created by a Transform step will silently skip this DTD.

For clarity, the “transform.” or “transform2.” parameter name prefix is omitted here.

However when you’ll pass any of the following parameters to w2x, please do not forget this prefix. Example: -p transform.cals-tables yes.

Parameters:

Name	Value	Description
xslt-url-or-file	An absolute URL or the path of an existing file. No default (required).	Specifies which XSLT 1.0 stylesheet should be used to transform the input XML document. A relative file path is relative to the current working directory.
out-file	A file path. No default (required).	Specifies the path of the save file. A relative file path is relative to the current working directory.

Name

Value

Description

xslt-url-or-file

An absolute URL or the path of an existing file.

No default (required).

Specifies which XSLT 1.0 stylesheet should be used to transform the input XML document. A relative file path is relative to the current working directory.

out-file

A file path.

No default (required).

Specifies the path of the save file. A relative file path is relative to the current working directory.

Any other parameter is passed to the XSLT stylesheet as an XSLT stylesheet parameter. Which XSLT stylesheet parameters are supported depend on the XSLT stylesheet being used.

Table 4 Parameters of w2x:xslt/docbook.xslt, docbook5.xslt, which are used to convert input XHTML document to DocBook v4 or v5

Name	Value	Description
docbook-version	DocBook version (“4.5”, “5.0”, “5.1” or “5.2”). Default: “4.5” for docbook.xslt, “5.0” for docbook5.xslt.	Specifies the version of DocBook. This number is used to specify which <!DOCTYPE> to add to the generate file or, in the case of DocBook 5, the value of the version attribute of the root element of the generated file. Please remember that versions of DocBook older than “4.3” do not support HTML tables. (HTML tables, not CALS tables, are generated by default. See below.)
cals-tables	“yes” \| “no”. Default: “no”.	If “yes”, generate CALS tables. If “no”, generate HTML tables. Note that cals-table=”yes” requires specifying Convert step parameter set-column-number=”yes”.
hierarchy-name	“book” \| “article” \| “part” \| “chapter” \| “appendix” \| “section” \| “book-sect1” \| “article-sect1” \| “part-sect1” \| “chapter-sect1” \| “appendix-sect1” \| “sect1” \| “sect2” \| “sect3” \| “sect4” \| “sect5” . Default: “book”.	Specifies the root element name and type of sections of the DocBook document to be generated.
media-alt	“yes” \| “no”. Default: “no”.	If “yes”, convert the alt attribute of XHTML element img to DocBook alt element. If “no”, ignore the alt attribute of XHTML element img.
pre-element-name	An element local name. Default: “literallayout”.	Specifies to which DocBook element, an HTML pre element is to be converted.

Table 5 Parameters of w2x:xslt/assembly.xslt, which are used to convert input DocBook V5.1 book to a DocBook V5.1 assembly

Name	Value	Description
add-index	“yes” \| “no”. Default: “yes”.	Ignored if the input book document does not contain any index term. If “yes”, add an index module at the end of the assembly. If “no”, do not add an index module at the end of the assembly.
output-path	An absolute or relative “file:” URI. No default (required).	Specifies the URI of the directory which is to contain all generated files. A relative URI is relative to the current working directory.
section-depth	“1”, “2”, “3”, “4”, “5”, “6”, “7”, “8”, “9”. Default: “1”.	Specifies the module structure of the assembly (always acting as a book) to be generated. Example 1: an assembly generated using section-depth=”1” only contains chapter modules. Example 2: an assembly generated using section-depth=”2” contains chapter modules, themselves possibly containing section modules. Example 3: an assembly generated using section-depth=”3” contains chapter modules, themselves possibly containing section modules, themselves possibly containing section modules (acting as subsections).
topic-path	An absolute or relative “file:” URI. No default: generate topic files in output-path.	Specifies the URI of the subdirectory directory which is to contain all generated DocBook V5.1 topic files. A relative URI is relative to output-path.

Table 6 Parameters of w2x:xslt/topic.xslt, which is used to convert input XHTML document to a DITA topic

Name	Value	Description
root-topic-id	An XML ID. Default: automatically generated ID.	Specifies the ID of the root topic.
single-topic	“yes” \| “no”. Default: “no”.	If “yes”, convert input <div class=”role-sectionN”> to (non-nested) DITA section elements. If “no”, convert input <div class=”role-sectionN”> to nested topics.
topic-type	“topic” \|“concept” \| “generalTask” \| “task” (same as: “strictTask” ) \| “reference”. Default: “topic”.	Specifies the type of topics to be created by the XSLT stylesheet.
pre-element-name	An element local name. Default: “pre”.	Specifies to which DITA element, an HTML pre element is to be converted.
shortdesc-class-name	A class name. Default: “”. Examples: p-Shortdesc, p-Abstract.	Specifies the class name of the XHTML <p> which acts as a short description of the section. When this parameter is not specified (or is specified as the empty string which is its default value), the following style mapping, created by the w2x-app wizard: -p edit.blocks.convert¬ "p-Shortdesc p class='p-Shortdesc'" ... <xsl:template match="h:p[@class='p-Shortdesc']"> <shortdesc> <xsl:call-template name="processCommonAttributes"/> <xsl:apply-templates/> </shortdesc> </xsl:template> causes DITA <shortdesc> elements to generated inside topic bodies, which is invalid. After specifying -p transform.shortdesc-class-name¬ p-Shortdesc this issue is fixed and DITA <shortdesc> elements are generated before topic bodies.

Table 7 Parameters of w2x:xslt/xhtml_strict.xslt, xhtml_loose.xslt, xhtml1_1.xslt, xhtml5.xslt, which are used to convert input XHTML 1.0 Transitional document to XHTML having a different version

Name	Value	Description
add-xml-lang	“yes” \| “no”. Default: “yes” for xhtml_strict, xhtml_loose, xhtml1_1; “no” for xhtml5.	If “yes”, add an xml:lang attribute to all XHTML elements having a lang attribute.
discard-index-terms	“yes” \| “no”. Default: “yes”.	If “yes”, discard <span class=”role-index-term”> elements. If “no”, keep <span class=”role-index-term”> elements.
footnote-number-format	A valid XSLT number format (value of attribute format of element xsl:number). Default: “[1]”.	When parameter number-footnotes is “yes”, specifies the format of the numeric label used for footnotes and footnote callouts.
generate-xref-text	“yes” \| “no”. Default: “yes”.	If “yes”, add hyperlink text to a elements which are cross-references. If “no”, keep empty a elements which are cross-references.
number-footnotes	“yes” \| “no”. Default: “yes”.	If “yes”, add a numeric label to footnotes and footnote callouts. If “no”, do not add a numeric label to footnotes and footnote callouts.
style-with-class	“yes” \| “no”. Default: “no”.	If “yes”, add a class attribute to some elements to allow using a CSS stylesheet to style them. For example: convert <center> to <div class=”center”>. If “no”, add a direct style to some elements to style them. For example: convert <center> to <div style=”text-align:center;”>.

Table 8 Parameters of w2x:xslt/map.xslt, bookmap.xslt, which are used to convert input DITA topic file to a map or bookmap

Name	Value	Description
add-index	“yes” \| “no”. Default: “yes”.	bookmap.xslt only. Ignored if the input topic document does not contain any index term. If “yes”, add an indexlist element to the back matter of the bookmap . If “no”, do not add an indexlist element to the back matter of the bookmap.
add-toc	“yes” \| “no”. Default: “yes”.	bookmap.xslt only. If “yes”, add a toc element to the front matter of the bookmap. If “no”, do not add a toc element to the front matter of the bookmap.
output-path	An absolute or relative “file:” URI. No default (required).	Specifies the URI of the directory which is to contain all generated files. A relative URI is relative to the current working directory.
section-depth	“1”, “2”, “3”, “4”, “5”, “6”, “7”, “8”, “9”. Default: “1”.	Specifies the topicref structure of the DITA map to be generated. Example 1: a bookmap generated using section-depth=”1” only contains chapter topicrefs. Example 2: a bookmap generated using section-depth=”2” contains chapter topicrefs, themselves possibly containing plain topicrefs (acting as sections). Example 3: a bookmap generated using section-depth=”3” contains chapter topicrefs, themselves possibly containing plain topicrefs (acting as sections), themselves possibly containing other plain topicrefs (acting as subsections).
topic-path	An absolute or relative “file:” URI. No default: generate topic files in output-path.	Specifies the URI of the subdirectory directory which is to contain all generated topic files. A relative URI is relative to output-path.
topic-type	“topic” \| “concept” \| “generalTask” \| “task” (same as: “strictTask” ) \| “reference”. No default. See description.	Specifies the type of topics to be created by the topic.xslt XSLT stylesheet. See above. This parameter is used to make a difference between a strict task and a general task. In all other cases, this parameter may be omitted.