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.

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 (e.g. “4.5” or “5.0”).

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/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 6 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

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 7 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.