First page Previous page Part I, Chapter 3. The ditac command-line utility Part I, Chapter 4. XSLT stylesheets parameters (9 / 19) Part II. Customizing the output of XMLmind DITA Converter Next page Last page

Chapter 4. XSLT stylesheets parameters Previous topic Parent topic Child topic Next topic

Parameters common to all stylesheets

Note Parameters marked using this icon systemParam.png are system parameters. They are automatically specified by the application executing the XSLT stylesheets. Such system parameters must not be specified by the end-user. Such system parameters are documented here only because the end-user may see them referenced in some configuration files.
Parameter Value Description
systemParam.pngditacListsURI
URL(1).
Default value: output_dir/ditac_lists.ditac_lists.
The URL of file ditac_lists.ditac_lists.
title-page
Allowed values are: 'auto', 'none' or the URI of a custom title page.
Default value: 'auto'.
Specifies the kind of ``title page'' (contains the title of the document, its author, etc) to be generated before the actual contents of the document.
'auto'
Automatically generate a title page based on the title and metadata of the map.
'none'
Do not generate a title page.
URI of a custom title page
Specifies the URI of a custom title page. If the URI is relative, it is relative to the current working directory of the user.
This custom title page is an XHTML file for XHTML-based formats (XHTML, HTML Help, etc). This custom title page is an XSL-FO file for FO-based formats (PDF, RTF, etc). Such custom title pages are generally hand-written.
  • The child nodes of the body element of the custom XHTML title page are wrapped in a div contained in the XHTML/HTML file being generated by the XSLT stylesheet.
    Do not add a <!DOCTYPE> to such custom XHTML title page because otherwise, the XSLT stylesheet may fail loading it.
    See sample custom XHTML title page Opens in new window.
  • The child nodes of the first fo:flow[@flow-name='xsl-region-body'] element of the custom XSL-FO title page are wrapped in a fo:block contained the XSL-FO file being generated by the XSLT stylesheet.
    See sample custom XSL-FO title page Opens in new window.
number
List of values separated by whitespace. Allowed values are: 'topic', 'chapter-only', 'table', 'fig', 'example', 'all'.
Default value: '' (number nothing).
Specifies which elements are to be numbered.
'chapter-only' means: number topics, but only those referenced in a bookmap as part, chapter and appendix.
part-number-format
Allowed values are: 'I', 'i', 'A', 'a', '1'.
Default value: 'I'.
The number format of topics referenced in a bookmap as part. By default, such topics are numbered as follows: Part I. Title of first part, Part II. Title of second part, etc.
appendix-number-format
Allowed values are: 'I', 'i', 'A', 'a', '1'.
Default value: 'A'.
The number format of topics referenced in a bookmap as appendix. By default, such topics are numbered as follows: Appendix A. Title of first appendix, Appendix B. Title of second appendix, etc.
prepend-chapter-to-section-number
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Normally topics which are descendants of chapters (that is, topics referenced in a bookmap as chapter) are numbered as follows: 1. Title of first section, 1.1. Title of first subsection, etc.
Specifying prepend-chapter-to-section-number='yes' prepends the number of the chapter ancestor to the section number. This gives for example (for descendants of chapter 5): 5.1. Title of first section, 5.1.1. Title of first subsection, etc.
number-separator1
String.
Default value: '.'.
The string used to separate the hierarchical number of topics acting as sections.
number-separator2
String.
Default value: '-'.
The string used to separate the hierarchical number of figures, tables and examples.
When possible, the number of figure, table or example is made relative to the number of the ancestor chapter or appendix. This gives for example (for descendants of chapter 5): Figure 5-1. Title of first figure of chapter 5, Figure 5-2. Title of second figure of chapter 5, etc.
title-prefix-separator1
String.
Default value: '. '.
The string used to separate the number of an formal object from its title.
center
List of element names separated by whitespace.
Example: 'fig simpletable table'.
Default value: ''.
Specifies which elements are to be centered horizontally on the page.
title-after
List of element names separated by whitespace.
Example: 'fig table'.
Default value: ''.
Specifies which elements should have their titles displayed after their bodies.
xsl-resources-directory
URL. A relative URL is relative to the output directory.
Default value: 'resources/' resolved against the directory which contains the XSLT stylesheets.
Most XSLT stylesheets generate files which reference resources such as icons or CSS stylesheets. This parameter specifies the target directory which is to contain such resources.
If this directory does not exist, it is automatically created.
If this directory does not already contain the resources needed by the XSLT stylesheets, such resources are automatically copied to this directory.
The default value of this parameter is something like file:/opt/ditac/xsl/xhtml/resources/ for the stylesheets generating XHTML. URL file:/opt/ditac/xsl/xhtml/resources/ specifies an existing directory containing basic.css, note.png, important.png, etc. This means that by default, no directory is created and no resource is copied.
Important
  • Explicitly specifying something like xsl-resources-directory='res' is almost always required when generating files having an XHTML/HTML based format (XHTML, HTML Help, etc).
  • Explicitly specifying something like xsl-resources-directory='res' is almost never required when generating files converted from XSL-FO (PDF, RTF, etc).
use-note-icon
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether icons should be used rather than text in order to represent the label of a note element.
note-icon-list
List of type attribute values separated by whitespace.
Default value: 'attention caution danger fastpath important note notes remember restriction tip'.
Specifies the type (attribute type) of the note elements for which icons should be used rather than text in order to represent note labels.
Ignored unless use-note-icon='yes'.
note-icon-suffix
Default value: '.png'.
The suffix of a note icon.
The root name of a note icon should be identical to the value of the type attribute it represents. For example, if note-icon-suffix='.svg', the default resources directory is expected to contain note.svg, important.svg, caution.svg, etc.
In principle, there is no need for an end-user to specify any of the note-icon-suffix, note-icon-width or note-icon-height parameters.
note-icon-width
Length. A length may have a unit. Default is px.
Default value: '32'. '7mm' for the XSLT stylesheets that generate XSL-FO.
The width of a note icon.
note-icon-height
Length. A length may have a unit. Default is px.
Default value: '32'. '7mm' for the XSLT stylesheets that generate XSL-FO.
The height of a note icon.
xref-auto-text
List of values separated by whitespace. Allowed values are: 'number' and 'text'.
Default value: 'number'.
This parameter specifies which text to generate for an xref element, when this xref element contains no text at all(2).
Let's suppose that an xref element containing no text at all points to a topic titled "Installation".
Because the xref element points to an element having a title child element, ditac may use this title as a starting point for the generated text.
Now let's suppose that topics are numbered and that the number of the "Installation" topic is "Chapter 5".
The text generated for this xref element is thus:
If xref-auto-text='number'
Chapter 5
If xref-auto-text='text'
Installation
If xref-auto-text='number text'
Chapter 5. Installation
Note that this specification is just a hint because ditac needs anyway to generate some text. For example, if topics are not numbered and xref-auto-text='number', the generated text will be "Installation".
link-auto-text
List of values separated by whitespace. Allowed values are: 'number' and 'text'.
Default value: 'number text'.
This parameter specifies which text to generate for a link element, when this link element has no linktext child element or when this linktext child element is empty.
Similar to above parameter xref-auto-text but for link elements.
show-draft-comments
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether draft-comments elements should be rendered.
index-range-separator
String.
Default value: '&#x2013;' (EN DASH).
The string used to separate the first page number from the last page number in a page range of an indexed term. Example: index-range-separator='<-->': 
C
Cat 54, 87<-->90

Parameters common to the stylesheets that basically generate XHTML or HTML

This applies to the stylesheets that generate XHTML 1.0, XHTML 1.1, HTML, Java™ Help, HTML Help, Eclipse Help, EPUB.
Parameter Value Description
screen-resolution
Positive integer.
Default value: '96'.
The resolution of the screen in dot per inch (DPI). This resolution is used to convert image dimensions such as 3cm to pixels.
default-table-width
A percentage, typically something like '100%' or '90%'.
Default value: '' (as narrow as possible).
The default width of table and simpletable elements.
chain-pages
Allowed values are: 'none', 'top', 'bottom' or 'both'.
Default value: 'none'.
Specifies whether a header and/or a footer containing navigation icons should be generated in order to link together all the HTML pages.
Note Do not specify any value other than 'none' when generating HTML Help, Eclipse Help, EPUB and Java™ Help.
chain-topics
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether navigation icons should be generated in order to link together all the topics.
Note Do not specify any value other than 'no' when generating HTML Help, Eclipse Help, EPUB and Java™ Help.
css-name
URL basename relative to the directory specified by parameter xsl-resources-directory.
Default value: 'basic.css'; 'javahelp.css' when the output format is Java™ Help.
Specifies which CSS stylesheet to use. This CSS stylesheet is expected to be found in the resources directory.
Restriction
Not supported by the stylesheets that generate EPUB.
css
URL.
Default value: ''.
Specifies which CSS stylesheet to use. Has priority over the CSS stylesheet specified by the css-name parameter.
An end-user wishing to use a custom CSS must typically:
  1. Import the basic.css stock stylesheet in its own custom.css as follows:
    @import url(basic.css);
  2. Invoke ditac with the following parameters: xsl-resources-directory='res', css='res/custom.css'.
  3. Copy by hand custom.css to output_dir/res/ after ditac has finished its job.
Restriction
Not supported by the stylesheets that generate EPUB.
navigation-icon-suffix
String.
Default value: '.png'.
The suffix of a navigation icon.
The root names of navigation icons are fixed:
  • first, first_disabled,
  • last, last_disabled,
  • next, next_disabled,
  • previous, previous_disabled,
  • parent, parent_disabled,
  • child, child_disabled.
For example, if note-icon-suffix='.svg', the default resources directory is expected to contain first.svg, first_disabled.svg, last.svg, etc.
In principle, there is no need for an end-user to specify any of the navigation-icon-suffix, navigation-icon-width or navigation-icon-height parameters.
navigation-icon-width
Length. A length may have a unit. Default is px.
Default value: '16'.
The width of a navigation icon.
navigation-icon-height
Length. A length may have a unit. Default is px.
Default value: '16'.
The height of a navigation icon.
mark-external-links
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether an external link should be marked using a ``opens in new window'' icon.
external-link-icon-suffix
Basename.
Default value: 'new_window.png'.
The basename of the ``opens in new window'' icon. This icon is found in the resources directory..
external-link-icon-width
Length. A length may have a unit. Default is px.
Default value: '11'.
The width of the ``opens in new window'' icon.
external-link-icon-height
Length. A length may have a unit. Default is px.
Default value: '10'.
The height of the ``opens in new window'' icon.

Parameters common to the stylesheets that generate Java™ Help, HTML Help, Eclipse Help and EPUB

Parameter Value Description
add-toc-root
Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
If 'yes', add a pseudo TOC entry, bearing the title of the document, containing all the actual TOC entries.
Restriction
  • Value 'no' is not supported by the stylesheets that generate Eclipse Help.
  • Ignored by the stylesheets that generate EPUB.
number-toc-entries
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
If 'yes', number the TOC entries. No effect unless the number parameter is used to specify that topics should be numbered.

Parameters specific to the stylesheets that generate Java™ Help

In principle, there is no need for an end-user to specify any of the following parameters.
Parameter Value Description
helpset-basename
URL basename.
Default value: 'jhelpset.hs'.
Basename of the Java™ Help HelpSet file.
map-basename
URL basename.
Default value: 'jhelpmap.jhm'.
Basename of the Java™ Help Map file.
toc-basename
URL basename.
Default value: 'jhelptoc.xml'.
Basename of the Java™ Help Contents file.
index-basename
URL basename.
Default value: 'jhelpidx.xml'.
Basename of the Java™ Help Index file.
indexer-directory-basename
URL basename.
Default value: 'JavaHelpSearch'.
Basename of the directory which will contain the data generated by running jhindexer. A properly quoted relative URL, not a filename.

Parameters specific to the stylesheets that generate HTML Help

In principle, there is no need for an end-user to specify any of the following parameters.
Parameter Value Description
systemParam.pngchmBasename
URL basename.
Default value: 'help.chm'.
Basename of the compiled HTML Help file.
systemParam.pnghhpBasename
URL basename.
Default value: 'project.hhp'.
Basename of the HTML Help project file.
hhc-basename
URL basename.
Default value: 'toc.hhc'.
Basename of the HTML Help contents file.
hhx-basename
URL basename.
Default value: 'index.hhx'.
Basename of the HTML Help index file.
hhp-template
URL basename.
Default value: 'template.hhp' resolved against the directory which contains the XSLT stylesheets.
URL of the file containing the template of the HTML Help project file. This plain text file encoded in UTF-8 contains variables such as %compiledFile%, %contentsFile%, %defaultTopic%, etc, which are substituted with their values.

Parameters specific to the stylesheets that generate Eclipse Help

Parameter Value Description
plugin-name
String
No default value.
The name of the plug-in, typically the title of the document. Example: 'ACME Widget User&apos;s Guide'.
plugin-id
String
No default value.
An ID uniquely identifying the plug-in, typically a Java-like fully qualified name. Example: 'com.acme.widget.userguide'.
Important
The subdirectory of plugins/ containing the plug-in must have the same basename as the value of parameter plugin-id.
plugin-provider
String
No default value.
The author, company or organization which has contributed the plug-in. Example: 'ACME Corp.'.
plugin-version
String
Default value: '1.0.0'.
The version of the plug-in.
plugin-toc-basename
URL basename.
Default value: 'toc.xml'.
Basename of the table of contents file.
plugin-index-basename
URL basename.
Default value: 'index.xml'.
Basename of the index file.

Parameters specific to the stylesheets that generate EPUB

Parameter Value Description
epub-identifier
String
Default value: dynamically generated UUID URN.
A globally unique identifier for the generated EPUB document (typically the permanent URL of the EPUB document).

Parameters specific to the stylesheets that generate XSL-FO

The XSL-FO file generated by the XSLT stylesheets is converted to PDF, PostScript®, RTF, WordprocessingML, Office Open XML (.docx), OpenOffice (.odt) by the means of XSL-FO processors such as Apache FOP Opens in new window, RenderX XEP Opens in new window, Antenna House XSL Formatter Opens in new window or XMLmind XSL-FO Converter Opens in new window.
Parameter Value Description
systemParam.pngfoProcessor
String. Examples: 'FOP', 'XEP', 'XFC'.
Default value: ''.
The name of the XSL-FO processor used to convert the XSL-FO file generated by the XSLT stylesheets to the target output format.
base-font-size
Default value: '10pt'.
The size of the ``main font'' of the document. All the other font sizes are computed relatively to this font size
justified
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether text (e.g. in paragraphs) should be justified (that is, flush left and right) or just left aligned (that is, flush left and ragged right).
hyphenate
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether words may be hyphenated.
show-external-links
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether the external URL referenced by an xref or link element should be displayed right after the text contained by this element.
Example: show-external-links='yes'causes <xref href="http://www.oasis-open.org/">Oasis</xref> to be rendered as follows: Oasis [http://www.oasis-open.org/].
external-href-before
String.
Default value: ' ['.
Separates the text of an xref or link element from its referenced external URL. Ignored unless show-external-links='yes'.
external-href-after
String.
Default value: ']'.
Appended after the external URL referenced by an xref or link element. Ignored unless show-external-links='yes'.
show-xref-page
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether the page number corresponding to the internal link target referenced by an xref element should be displayed right after the text contained by this element.
Example: show-xref-page='yes'causes <xref href="introduction.dita">Introduction</xref> to be rendered as follows: Oasis [3].
show-link-page
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Same as show-xref-page but for link elements.
page-ref-before
String.
Default value: ' ['.
Separates the text of an xref or link element from the page number it points to. Ignored unless show-xref-page='yes' or show-link-page='yes'.
page-ref-after
String.
Default value: ']'.
Appended after the page number pointed to by an xref or link element. Ignored unless show-xref-page='yes' or show-link-page='yes'.
header-left
A mix of text and variables.
Default value: '' (empty).
Specifies the textual contents of the left part of a page header. The width of this part is 20% of the overall width of the page header.
This parameter contains a mix of text and variables. Supported variables are:
%document-title%
The title of the document.
%chapter-title%
The title of the last topic being rendered, when this topic is acting as a part, chapter or appendix .
%page-number%
Current page number.
%odd-page-number%
Current page number; empty when a double-sided output is being generated and the current page number is even.
%even-page-number%
Current page number when a double-sided output is being generated and the current page number is even; empty otherwise.
%page-count%
Total number of pages of the current document division (front matter, body matter or back matter).
If you need to specify character '%' in a header or footer, then quote this character by doubling it. Example: '100%% Java'.
header-center
A mix of text and variables.
Default value: '%document-title%'.
Specifies the textual contents of the central part of a page header. The width of this part is 60% of the overall width of the page header.
header-right
A mix of text and variables.
Default value: '' (empty).
Specifies the textual contents of the right part of a page header. The width of this part is 20% of the overall width of the page header.
header-separator Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Specifies whether an horizontal rule should be drawn below the page header.
footer-left
A mix of text and variables.
Default value: '%even-page-number%'.
Same as header-left, but for the page footer.
footer-center
A mix of text and variables.
Default value: '%chapter-title%'.
Same as header-center, but for the page footer.
footer-right
A mix of text and variables.
Default value: '%odd-page-number%'.
Same as header-right, but for the page footer.
footer-separator Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Specifies whether an horizontal rule should be drawn above the page footer.
header-left-image
URI (possibly relative to the current working directory of the user) of a graphics file.
Default value: '' (empty).
Specifies the image contents of the left part of a page header. This supersedes the corresponding textual contents specified using parameter header-left.
The image is displayed at its intrinsic size. If it is too tall to fit in a page header or footer, you may need to increase the height of the header or footer by using the following parameters: header-height, body-top-margin, footer-height, body-bottom-margin.
header-center-image
URI (possibly relative to the current working directory of the user) of a graphics file.
Default value: '' (empty).
Specifies the image contents of the central part of a page header. This supersedes the corresponding textual contents specified using parameter header-center.
header-right-image
URI (possibly relative to the current working directory of the user) of a graphics file.
Default value: '' (empty).
Specifies the image contents of the right part of a page header. This supersedes the corresponding textual contents specified using parameter header-right.
footer-left-image
URI (possibly relative to the current working directory of the user) of a graphics file.
Default value: '' (empty).
Same as header-left-image, but for the page footer.
footer-center-image
URI (possibly relative to the current working directory of the user) of a graphics file.
Default value: '' (empty).
Same as header-center-image, but for the page footer.
footer-right-image
URI (possibly relative to the current working directory of the user) of a graphics file.
Default value: '' (empty).
Same as header-right-image, but for the page footer.
pdf-outline
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether PDF bookmarks should be generated.
Supported by both the 'XEP' and 'FOP' XSL-FO processors. Not relevant, and thus ignored by 'XFC'.
paper-type
Allowed values are: 'Letter', 'Legal', 'Ledger', 'Tabloid', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10', 'B0', 'B1', 'B2', 'B3', 'B4', 'B5', 'B6', 'B7', 'B8', 'B9', 'B10', 'C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8', 'C9', 'C10' (case-insensitive).
Default value: 'A4'.
A convenient way to specify the size of the printed page.
It is also possible to specify a custom paper type by ignoring the paper-type parameter and directly specifying the page-width and page-height parameters.
page-orientation
Allowed values are: 'portrait' and 'landscape'.
Default value: 'portrait'.
The orientation of the printed page .
page-width
Length. Example: '8.5in'.
Default value: depends on paper-type.
The width of the printed page.
page-height
Length. Example: '297mm'.
Default value: depends on paper-type.
The height of the printed page.
two-sided
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether the document should be printed double sided.
page-top-margin
Length.
Default value: '0.5in'.
See Figure 4-1 below.
page-bottom-margin
Length.
Default value: '0.5in'.
See Figure 4-1 below.
page-inner-margin
Length.
Default value: if parameter two-sided is specified as 'yes' then '1.25in' otherwise '1in'.
See Figure 4-1 below.
page-outer-margin
Length.
Default value: if parameter two-sided is specified as 'yes' then '0.75in' otherwise '1in'.
See Figure 4-1 below.
body-top-margin
Length.
Default value: '0.5in'.
See Figure 4-1 below.
body-bottom-margin
Length.
Default value: '0.5in'.
See Figure 4-1 below.
header-height
Length.
Default value: '0.4in'.
See Figure 4-1 below.
footer-height
Length.
Default value: '0.4in'.
See Figure 4-1 below.
index-column-count
Positive integer.
Default value: '2'.
The number of columns of index pages.
index-column-gap
Length.
Default value: '12pt'.
The distance which separates columns in index pages.

Figure 4-1. Page areas

page_areas.png
 (1) Unlike a filename, an URL must contain properly quoted characters. For example, do not specify 'Hello world.htm', instead specify 'Hello%20world.htm'.
 (2) This implies that the xref-auto-text parameter is ignored when an xref element contains some text.
First page Previous page Part I, Chapter 3. The ditac command-line utility Part I, Chapter 4. XSLT stylesheets parameters (9 / 19) Part II. Customizing the output of XMLmind DITA Converter Next page Last page