Previous page Part I, Chapter 3. The ditac command-line utility Part I, Chapter 4. XSLT stylesheets parameters (10 / 32)   Table of Contents   Index Part I, Chapter 4, Section 1. Page headers and footers Next page

Chapter 4. XSLT stylesheets parameters

§ Parameters common to all stylesheets

Note
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.
  • Parameters marked using this icon pseudoParam.png are pseudo-parameters. They may or may not be passed to the XSLT stylesheets, but the important thing to remember is that they are also interpreted by ditac itself. By consequence, you cannot specify them in an XSLT stylesheet which customizes the stock ones (as explained in Part II, Chapter 9, Section 2).
Parameter Value Description
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.
cause-number-format
Allowed values are: 'I', 'i', 'A', 'a', '1'.
Default value: 'A'.
In a <troubleshooting> topic, multiple <remedy> elements having no title are given numbers formatted using this format.
center
List of element names separated by whitespace.
Example: 'fig equation-figure simpletable table'.
Default value: ''.
Specifies which elements are to be centered horizontally on the page.
systemParam.pngditacListsURI
URL(1).
Default value: output_dir/ditac_lists.ditac_lists.
The URL of file ditac_lists.ditac_lists.
equation-number-after
String.
Default value: ')'.
Text added after the contents of a <equation-number> element.
equation-number-before
String.
Default value: '('.
Text added before the contents of a <equation-number> element.
extended-toc
Allowed values are: 'frontmatter', 'backmatter', 'both', 'none'.
Default value: 'none'.
Allows to add <frontmatter> and <backmatter> <topicref>s to the Table of Contents (TOC) of a document.
Note that the @toc, @navtitle, @locktitle, etc, attributes are applied normally to <frontmatter> and <backmatter> <topicref>s when an extended TOC is generated.
external-resource-base
Allowed values are: '', an URL ending with "/" or '#REMOVE'.
Default value: '#REMOVE' for EPUB 2 and EPUB 3, '' for all the other output formats.
Specifies how to resolve <xref> or <link> elements having an external @scope attribute and a relative @href attribute. Example of such <xref> elements: <xref scope="external" format="java" href="src/Test.java">Test.java</xref>.
''
Do not resolve the @href attribute. In this case, the external resource files are expected to be copied “by hand” to the output directory.
An URL ending with "/"
This URL is prepended to the value of the @href attribute.
'#REMOVE'
The <xref> or <link> element is processed as if it did not have an @href attribute.
highlight-source
Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Allows to turn off syntax highlighting in elements specializing <pre>.
By default, syntax highlighting is turned on for all elements specializing <pre> and having an @outputclass attribute equals to language-c, language-cpp, language-csharp, language-delphi, language-ini, language-java, language-javascript, language-m2, language-perl, language-php, language-python, language-ruby, language-tcl.
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
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.
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'.
number
List of values separated by whitespace. Allowed values are: 'topic', 'chapter-only', 'table', 'fig', 'example', 'equation-figure', 'all'.
Default value: '' (number nothing).
Specifies which elements are to be numbered.
'all' is a short form for 'topic table fig equation-figure'.
'chapter-only' means: number topics, but only those referenced in a bookmap as <part>, <chapter> and <appendix>.
Note
Note
Please note that 'all' does not include 'example'. If you want to number all formal elements including examples, then you must specify 'all example'.
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, examples and equations.
When possible, the number of figure, table, example or equation 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.
mark-important-steps
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
 Generates a "Required" (respectively "Optional") label for <step> and <substep> elements having an @importance attribute set to "required" (resp. "optional").
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.
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.
remedy-number-format
Allowed values are: 'I', 'i', 'A', 'a', '1'.
Default value: 'A'.
In a <troubleshooting> topic, multiple <remedy> elements having no title are given numbers formatted using this format.
show-draft-comments
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether <draft-comments> elements should be rendered.
troubleSolution-number-format
Allowed values are: 'I', 'i', 'A', 'a', '1'.
Default value: '1'.
In a <troubleshooting> topic, multiple <troubleSolution> elements having no title are given numbers formatted using this format.
title-after
List of element names separated by whitespace.
Example: 'fig equation-figure table'.
Default value: ''.
Specifies which elements should have their titles displayed after their bodies.
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.
title-prefix-separator1
String.
Default value: '. '.
The string used to separate the number of an formal object from its title.
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.
watermark-image
URI. If the URI is relative, it is relative to the current working directory of the user.
No default value.
Specifies an image file which is to be used as a watermark in all the pages comprising the output document. See also parameter watermark.
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".
For XSL-FO based output formats, see also parameter show-xref-page.
pseudoParam.pngxsl-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.
If the value of this parameter is an absolute URI, then ditac assumes that no resource directory is to be created and no resource is to be copied because this has already been done by the user.
Important
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).

§ Parameters common to the stylesheets that basically generate XHTML or HTML

This applies to the stylesheets that generate XHTML, HTML, Web Help, HTML Help, Eclipse Help, EPUB.
Parameter Value Description
add-copiable-links
List of values separated by whitespace. Allowed values are: 'topic', 'table', 'fig', 'equation-figure', 'example', section', 'all' (equivalent to 'topic table fig equation-figure example section').
Default value: '' (do not add copiable links).
Adds a copiable link to the <title> child elements of specified “formal elements”.
  • If the “formal element” is numbered (e.g. has a "Chapter 1." automatically generated label), then the automatically generated label is converted to a link. This link points to the formal element (e.g. a link to the <topic> having a chapter role).
  • Otherwise (e.g. a <section> which cannot be numbered), a link containing the section symbol, "§", is added to the <title>. This link points to the formal element (e.g. a link to the <section>).
This automatically generated link to a formal element is intended to be copied using the "Copy Link" entry found in the contextual menu of all web browsers in order to be shared with others. For example, send this link by email.
Restriction
Restriction
  • For this facility to work, the formal element must have an @id attribute, whether specified by the author or automatically generated by ditac.
  • This parameter is ignored when generating HTML Help, Eclipse Help and EPUB.
add-index-toc
Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Specifies whether an A-Z list should be added at the beginning of the back-of-the-book index.
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
Note
There is no need to specify a value other than 'none' when generating Web Help, HTML Help, Eclipse Help and EPUB.
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.
See also related parameter: ignore-navigation-links.
Note
Note
There is no need to specify a value other than 'no' when generating Web Help, HTML Help, Eclipse Help and EPUB.
css
URL.
Default value: ''.
Low-level parameter specifying which CSS stylesheet to use to style the generated (X)HTML pages.
When neither css nor custom-css is specified, the default CSS stylesheet being used is xsl-resources-directory/base.css.
Restriction
Restriction
Not supported by the stylesheets that generate EPUB.
cssResourceName
URL basename relative to the directory specified by parameter xsl-resources-directory.
Default value: 'base.css'.
Very low-level parameter specifying which CSS stylesheet to use. This CSS stylesheet is expected to be found in the resources directory.
Note
Note
This parameter is not useful unless you develop a plug-in implementing a DITA specialization. More information in Part II, Chapter 10.
pseudoParam.pngcustom-css
URL.
Default value: ''.
Specifies the custom CSS stylesheet used to style the generated (X)HTML pages. This high-level parameter has priority over low-level parameter css.
This custom CSS stylesheet is copied to directory xsl-resources-directory. Therefore custom-css requires directory xsl-resources-directory to be specified as an URL which is relative to the output directory (e.g. xsl-resources-directory='res').
How to use custom-css is explained in Part II, Chapter 9, Section 1.
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.
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.
external-link-icon-name
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: '10'.
The width of the “opens in new window”' icon.
format-to-type
Zero or more DITA format/MIME type pairs. Example: "txt text/plain xml application/xml html text/html".
Default value: '', which means that DITA xref/@format is not converted to XHTML a/@type.
Allows to map DITA xref/@format to XHTML a/@type.
Using default empty value, <xref scope="external" format="txt" href="http://acme.com/info.xyz"> is converted to <a href="http://acme.com/info.xyz" target="_blank">. The fact that file extension ".xyz" is unknown may cause problems when attempting to navigate or download file "info.xyz" using a Web browser.
If -p format-to-type "txt text/plain" is passed to ditac then <xref scope="external" format="txt" href="http://acme.com/info.xyz"> is converted to <a type="text/plain" href="http://acme.com/info.xyz" target="_blank">, which is better.
generator-info
String
Default value: 'XMLmind DITA Converter VERSION'.
The name of the software which has been used to create the HTML pages.
Specify an empty string if you don't want to have a <meta name="generator" content="XXX"/> element added to your HTML pages.
ignore-navigation-links
Allowed values are: 'yes', 'no' and 'auto'.
Default value: 'auto' for XHTML and its variants; 'yes' for Web Help, HTML Help, Eclipse Help and EPUB
If 'yes', do not generate the navigation links corresponding to topicref attribute @collection-type.
If 'no', generate the navigation links corresponding to topicref attribute @collection-type.
If 'auto', generate the navigation links corresponding to topicref attribute @collection-type, unless chain-topics=yes.
javascripts
String. List of URLs separated by whitespace.
Default value: ''.
The URLs specified in this parameter must point to JavaScript files. These URLs are converted to <script> XHTML elements added to the <html>/<head> elements of the XHTML files generated by ditac.
Note that an URL may end with ';async', ';defer' or a combination of both flags. These flags are translated to the corresponding attributes of the <script> element. Example:
https://cdn.jsdelivr.net/npm/¬
mathjax@3/es5/tex-mml-chtml.js;async
is translated to:
<script type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/¬
mathjax@3/es5/tex-mml-chtml.js"
  async="async"></script>
mathjax
Allowed values are: 'yes', 'no' and 'auto'.
Default value: 'no'.
MathJax Opens in new window is a JavaScript display engine for mathematics that works in all browsers.Though a number of web browsers natively support embedded MathML, it's recommended to specify parameter mathjax=yes or mathjax=auto to let MathJax render embedded MathML found in the generated XHTML 5 and XHTML 5 Web Help files.
'yes'
Add a <script> XHTML element loading MathJax to the <html>/<head> elements of all XHTML files generated by ditac.
'auto'
Same as 'yes', but add <script> only to generated XHTML files containing MathML and/or TeX/LaTeX math.
Ignored by all XHTML-based formats but XHTML and Web Help.
mathjax-url
String.
Default value: the URL pointing to a MathJax CDN, as recommended in the MathJax documentation.
The URL allowing to load the MathJax Opens in new window engine configured for rendering MathML.
Ignored unless parameter mathjax is set to 'yes'or 'auto'.
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.
navigation-icon-height
Length. A length may have a unit. Default is px.
Default value: '16'.
The height of a navigation icon.
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.
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.
xhtml-mime-type
A MIME type without a parameter such as 'text/html', 'application/xhtml+xml', 'application/xml' or the empty string ('').
Default value: see prose.
Low-level parameter. Do not change default value unless you know what you are doing.
  • Specify 'text/html' to serve XHTML as HTML. This is the default value for all (X)HTML-based output formats except for EPUB 2 and (X)HTML5.
  • Specify 'application/xhtml+xml' if you prefer to serve XHTML as XML. This is the default value for EPUB 2.
  • Specify an empty string if you prefer not to generate <meta http-equiv="Content-Type">. This is the default value for (X)HTML5 for which a <meta charset="UTF-8"> is generated instead.

§ Parameters common to the stylesheets that generate 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
Restriction
  • Value 'no' is not supported by the stylesheets that generate Eclipse Help.
  • Ignored by the stylesheets that generate Web Help and EPUB.
number-toc-entries
Allowed values are: 'yes' and 'no'.
Default value: 'yes' for Web Help, 'no' for the other formats.
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 Web Help

Parameter Value Description
pseudoParam.pngwh---CSS_VAR_NAME
String. A valid CSS property value.
No default.
This kind of parameter may be used to override any of the default values of the CSS variables Opens in new window specified in any of the NNtheme.css template files (all found in ditac_install_dir/whc_template/_wh/).
For example, the main NNtheme.css template file:
body {
  ...
  --navigation-width: 33%;
  ...
}
The wh---navigation-width CSS variable is used as follows in NNcommon.css, another CSS template file:
#wh-navigation {
  ...
  width: var(--navigation-width);
  ...
}
Therefore parameter wh---navigation-width may be used to give the navigation side of the generated Web Help a different initial width. Example: -p wh---navigation-width "25%".
More examples in "XMLmind Web Help Compiler Manual, Getting started Opens in new window".
pseudoParam.pngwh-collapse-toc
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether the TOC should be initially collapsed.
pseudoParam.pngwh-favicon
Filename or absolute URI of an image file. A relative filename is relative to the current working directory.
Specifies the favicon which is to be added to each page of the Web Help. A favicon is a small image displayed next to the page title in the browser tab.
This file is copied to output_directory/_wh/user/.
pseudoParam.pngwh-index-numbers
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether words looking like numbers are to be indexed.
Examples of such number-like words: 3.14, 3,14, 3times4equals12, +1, -1.0, 3px, 1,2cm, 100%, 1.0E+6, 1,000.00$.
pseudoParam.pngwh-inherit-font-and-colors
Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
When wh-inherit-font-and-colors is set to 'no', the navigation pane of the generated Web Help uses fonts and colors of its own, which will generally differ from those used for the content of the Web Help.
Setting wh-inherit-font-and-colors to 'yes' lets you use for the navigation pane the same fonts and colors as those used for the content of the Web Help.
So basically this parameter is a shorthand for:
-p wh---navigation-font-family inherit¬
-p wh---navigation-font-size inherit¬
-p wh---navigation-color inherit¬
-p wh---navigation-background-color inherit
See above wh---CSS_VAR_NAME parameters.
pseudoParam.pngwh-jquery
Relative or absolute URI. A relative URI is relative to the URI of a page of the Web Help.
Default value: absolute URI of the corresponding file found on the Google CDN.
Specifies the location of the JavaScript file containing jQuery Opens in new window . Example: 
https://code.jquery.com/¬
jquery-3.7.1.slim.min.js
Specifying an "https:" URL is recommended when the generated Web Help is stored on an HTTPS server.
pseudoParam.pngwh-local-jquery
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether all jQuery files should be copied to _wh/jquery/, where _wh/ is the directory containing the other Web Help files.
By default, the jQuery files are accessed from the Web (typically from a CDN).
Note that this parameter is applied after jQuery has been possibly customized using parameter wh-jquery. For example, "-p wh-jquery https://code.jquery.com/jquery-3.7.0.js" copies a file downloaded from https://code.jquery.com/ to _wh/jquery/.
pseudoParam.pngwh-layout
The name of a layout.
Default value: 'classic'.
Selects a layout for the generated Web Help.
For now, only 3 layouts are supported: classic, simple and corporate.
pseudoParam.pngwh-responsive-ui
Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Specifies whether the generated Web Help should be “responsive”, that is, whether it should adapt its layout to the size of the screen.
pseudoParam.pngwh-ui-language
"browser" or "document" or a language code conforming RFC 3066 Opens in new window. Examples: de, fr-CA.
Default value: 'browser'.
Specifies which language should be used for the messages (tab labels, button tool tips, etc) of the generated Web Help.
Default value "browser" means that this language is the one used by the Web browser for its own messages. This language may often be specified in the user preferences of the Web browser.
Value "document" means that the language of the document should be used.
A language code such as en, en-US, es, es-AR, etc, may be used to explicitly specify which language should be used.
pseudoParam.pngwh-use-stemming
Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Specifies whether stemming(3) should be used to implement the search facility. By default, stemming is used whenever possible, that is,
  1. when the main language of the document can be determined;
  2. when this main language is one of: Danish, Dutch, English, Finnish, French, German, Hungarian, Italian, Norwegian, Portuguese, Russian, Spanish, Swedish, Romanian, Turkish.
The main language of the document is specified by the @xml:lang attribute found on the root element of DITA map being converted; otherwise using the -lang command-line option; otherwise, it is assumed to be "en".
pseudoParam.pngwh-user-css
Filename or absolute URI of a CSS file. A relative filename is relative to the current working directory.
Specifies the user's CSS stylesheet which is to be added to each page of the Web Help.
This file is copied to output_directory/_wh/user/.
Sample user's CSS wh_resources/header_footer.css Opens in new window as used in the following example:
-p wh-user-header¬
wh_resources/header.html
-p wh-user-footer¬
wh_resources/footer.html
-p wh-user-css¬
wh_resources/header_footer.css
-p wh-user-resources¬
wh_resources/header_footer_files
pseudoParam.pngwh-user-footer
Filename or absolute URI of an XHTML file. A relative filename is relative to the current working directory.
Specifies the user's footer which is to be added to each page of the Web Help.
The content of the <body> element of wh-user-footer is inserted as is in the <div id="wh-footer"> found in each page of the Web Help.
Same remark as for parameter wh-user-header about the resources referenced by a user's footer.
Sample user's footer wh_resources/footer.html Opens in new window as used in the following example:
-p wh-user-header¬
wh_resources/header.html
-p wh-user-footer¬
wh_resources/footer.html
-p wh-user-css¬
wh_resources/header_footer.css
-p wh-user-resources¬
wh_resources/header_footer_files
More examples in "XMLmind Web Help Compiler Manual, Getting started Opens in new window".
pseudoParam.pngwh-user-header
Filename or absolute URI of an XHTML file. A relative filename is relative to the current working directory.
Specifies the user's header which is to be added to each page of the Web Help.
The content of the <body> element of wh-user-header is inserted as is in the <div id="wh-header"> found in each page of the Web Help.
If a user's header references resources (e.g. image files), then these resources must either be referenced using absolute URLs or these resources must be found in a user's resource directory and parameter wh-user-resources must be specified.
Example:
  • The user's resource directory is called header_footer_files/ and contains header_footer_files/200x100.png.
  • ditac is passed parameters: -p wh-user-resources PATH_TO/header_footer_files and -p wh-user-header PATH_TO/header.html.
  • header.html looks like this:
    <html>
...
<body>
...
<img src="_wh/user/header_footer_files/¬
logo200x100.png" />
...
</body>
</html>
    Notice the path used to reference logo200x100.png.
Sample user's header wh_resources/header.html Opens in new window as used in the following example:
-p wh-user-header¬
wh_resources/header.html
-p wh-user-footer¬
wh_resources/footer.html
-p wh-user-css¬
wh_resources/header_footer.css
-p wh-user-resources¬
wh_resources/header_footer_files
More examples in "XMLmind Web Help Compiler Manual, Getting started Opens in new window".
pseudoParam.pngwh-user-resources
Filename or absolute "file:" URI of a directory. URI schemes other than "file" (e.g. "http") are not supported for this parameter. A relative filename is relative to the current working directory.
Specifies a user's resource directory which is to be recursively copied to output_directory/_wh/user/.
This directory typically contains image files referenced by the user's header, footer or CSS stylesheet.
Sample user's resource directory wh_resources/header_footer_files/ Opens in new window as used in the following example:
-p wh-user-header¬
wh_resources/header.html
-p wh-user-footer¬
wh_resources/footer.html
-p wh-user-css¬
wh_resources/header_footer.css
-p wh-user-resources¬
wh_resources/header_footer_files
More examples in "XMLmind Web Help Compiler Manual, Getting started Opens in new window".
whc-index-basename
URL basename.
Default value: 'whc_index.xml'.
Basename of the Index XML input file of XMLmind Web Help Compiler.
In principle, there is no need for an end-user to specify this parameter.
whc-toc-basename
URL basename.
Default value: 'whc_toc.xml'.
Basename of the TOC XML input file of XMLmind Web Help Compiler.
In principle, there is no need for an end-user to specify this parameter.

§ 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.
hhc-basename
URL basename.
Default value: 'toc.hhc'.
Basename of the HTML Help contents 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.
systemParam.pnghhpBasename
URL basename.
Default value: 'project.hhp'.
Basename of the HTML Help project file.
hhx-basename
URL basename.
Default value: 'index.hhx'.
Basename of the HTML Help index file.

§ Parameters specific to the stylesheets that generate Eclipse Help

Parameter Value Description
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
Important
The subdirectory of plugins/ containing the plug-in must have the same basename as the value of parameter plugin-id.
plugin-index-basename
URL basename.
Default value: 'index.xml'.
Basename of the index file.
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-provider
String
No default value.
The author, company or organization which has contributed the plug-in. Example: 'ACME Corp.'.
plugin-toc-basename
URL basename.
Default value: 'toc.xml'.
Basename of the table of contents file.
plugin-version
String
Default value: '1.0.0'.
The version of the plug-in.

§ Parameters specific to the stylesheets that generate EPUB

Parameter Value Description
cover-image
URI. If the URI is relative, it is relative to the current working directory of the user.
No default value.
Specifies an image file which is to be used as the cover page of the EPUB file. This image must be a PNG or JPEG image. Its size must not exceed 1000x1000 pixels.
In theory, EPUB 3 also accepts SVG 1.1 cover images.
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).
epub2-compatible
Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Only applies to EPUB 3.
By default, the EPUB 3 files generated by ditac are made compatible with EPUB 2 readers. Specify 'no' if you don't need this compatibility.

§ 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/LibreOffice (.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.
Tip
Tip
Inserting a <?pagebreak?> processing-instruction in the topic source between paragraphs, notes, tables, lists, etc, may be used to force a page break when generating any of the output formats which uses XSL-FO as an intermediate format (PDF, RTF, DOCX, etc).
Parameter Value Description
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
body-bottom-margin
Length.
Default value: '0.5in'.
See Figure 4-1 below.
body-font-family
A string containing one or more font families separated by commas.
Default value: 'serif'.
Specifies the family of the font used for the text of all elements except topic titles.
body-start-indent
Length.
Default value: '2pc'.
Applies only to alternate XSLT stylesheet ditac_install_dir/xsl/fo/fo_indent.xsl.
This stylesheet:
  • Indents all blocks but topic and section titles by the value of XSLT stylesheet parameter body-start-indent. By default body-start-indent is 2pc.
  • Adds more vertical space after topic and section titles.
  • Only part, appendices, chapter and appendix titles are underlined.
This stylesheet is invoked by passing option -t ditac-xsl:fo/fo_indent.xsl to ditac. Example of its output: manual-fop.pdf Opens in new window.
body-top-margin
Length.
Default value: '0.5in'.
See Figure 4-1 below.
choice-bullets
A string containing one or more single characters separated by whitespace.
Default value: '&#x2022;' (BULLET).
Specify which bullet character to use for a <choice> element. Additional characters are used for nested <choice> elements.
Changing the value of this parameter may imply changing the font-family attribute of the attribute-set choice-label.
equation-block-equation-width
Length.
Default value: '90%'.
 In a numbered <equation-block> element, this parameter specifies the width of the column containing the equation.
equation-block-number-width
Length.
Default value: '10%'.
 In a numbered <equation-block> element, this parameter specifies the width of the column containing the <equation-number> element.
external-href-after
String.
Default value: ']'.
Appended after the external URL referenced by an <xref> or <link> element. Ignored unless show-external-links='yes'.
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'.
systemParam.pngfoProcessor
String. Examples: 'FOP', 'XEP', 'AHF', '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.
footer-center
String.
Specifies the contents of the central part of a page footer. See Specifying a header or a footer.
Supports a conditional specification.
Default value:
two-sides even:: {{chapter-title}};;
two-sides part||chapter||appendices||appendix odd::¬
{{section1-title}};;
one-side:: {{chapter-title}}
footer-center-width
String representing an integer larger than or equal to 1.
Default value: '6'.
Specifies the proportional width of the central part of a page footer. See Specifying a header or a footer.
Supports a conditional specification.
footer-height
Length.
Default value: '0.4in'.
See Figure 4-1 below.
footer-left
String.
Specifies the contents of the left part of a page footer. See Specifying a header or a footer.
Supports a conditional specification.
Default value:
two-sides even:: {{page-number}}
footer-left-width
String representing an integer larger than or equal to 1.
Default value: '2'.
Specifies the proportional width of the left part of a page footer. See Specifying a header or a footer.
Supports a conditional specification.
footer-right
String.
Specifies the contents of the right part of a page footer. See Specifying a header or a footer.
Supports a conditional specification.
Default value:
two-sides first||odd:: {{page-number}};;
one-side:: {{page-number}}
footer-right-width
String representing an integer larger than or equal to 1.
Default value: '2'.
Specifies the proportional width of the right part of a page footer. See Specifying a header or a footer.
Supports a conditional specification.
footer-separator Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Specifies whether an horizontal rule should be drawn above the page footer.
header-center
String.
Default value: '{{document-title}}'.
Specifies the contents of the central part of a page header. See Specifying a header or a footer.
Supports a conditional specification.
header-center-width
String representing an integer larger than or equal to 1.
Default value: '6'.
Specifies the proportional width of the central part of a page header. See Specifying a header or a footer.
Supports a conditional specification.
header-height
Length.
Default value: '0.4in'.
See Figure 4-1 below.
header-left
String.
Default value: ''.
Specifies the contents of the left part of a page header. See Specifying a header or a footer.
Supports a conditional specification.
header-left-width
String representing an integer larger than or equal to 1.
Default value: '2'.
Specifies the proportional width of the left part of a page header. See Specifying a header or a footer.
Supports a conditional specification.
header-right
String.
Default value: ''.
Specifies the contents of the right part of a page header. See Specifying a header or a footer.
Supports a conditional specification.
header-right-width
String representing an integer larger than or equal to 1.
Default value: '2'.
Specifies the proportional width of the right part of a page header. See Specifying a header or a footer.
Supports a conditional specification.
header-separator Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Specifies whether an horizontal rule should be drawn below the page header.
hyphenate
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether words may be hyphenated.
index-column-count
Positive integer.
Default value: '2'.
The number of columns of index pages.
index-column-gap
Length.
Default value: '2em'.
The distance which separates columns in index pages.
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).
link-bullet
A string containing a single character.
Default value: '&#x2022;' (BULLET).
Specify which character is inserted before the text of a <link> element.
Changing the value of this parameter may imply changing the font-family attribute of the attribute-set link-bullet.
menucascade-separator
A string containing a single character.
Default value: '&#x2192;' (RIGHTWARDS ARROW).
Specify which character is used to separate the child elements of a <menucascade> element.
Changing the value of this parameter may imply changing the font-family attribute of the attribute-set menucascade-separator.
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.
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.
page-bottom-margin
Length.
Default value: '0.5in'.
See Figure 4-1 below.
page-height
Length. Example: '297mm'.
Default value: depends on paper-type.
The height of the printed page.
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-orientation
Allowed values are: 'portrait' and 'landscape'.
Default value: 'portrait'.
The orientation of the printed page.
page-outer-margin
Length.
Default value: if parameter two-sided is specified as 'yes' then '0.75in' otherwise '1in'.
See Figure 4-1 below.
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'.
When both page-ref-after and page-ref-before are specified as the empty string, in fact, this specifies that the generated string must be the localized equivalent of "on page".
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-top-margin
Length.
Default value: '0.5in'.
See Figure 4-1 below.
page-width
Length. Example: '8.5in'.
Default value: depends on paper-type.
The width of the printed page.
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.
pdf-outline
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether PDF bookmarks should be generated.
Supported by the 'XEP' , 'FOP' and 'AHF' XSL-FO processors. Not relevant, and thus ignored by 'XFC'.
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/].
show-imagemap-links
Allowed values are: 'yes' and 'no'.
Default value: 'yes'.
Specifies whether a numbered list should be generated for an <imagemap> element, with one list item per <area> element.
A list item contains the link specified by the <area> element. No list items are generated for “dead areas” (<area> elements specifying no link at all).
show-link-page
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Same as show-xref-page but for <link> elements.
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: Introduction [3].
See also parameters xref-auto-text, page-ref-before, page-ref-after.
title-color
A string representing a color.
Default value: 'black'.
Specifies the color used for the text of topic (of any kind) titles.
title-font-family
A string containing one or more font families separated by commas.
Default value: 'sans-serif'.
Specifies the family of the font used for the text of topic (of any kind) titles.
two-sided
Allowed values are: 'yes' and 'no'.
Default value: 'no'.
Specifies whether the document should be printed double sided.
ul-li-bullets
A string containing one or more single characters separated by whitespace.
Default value: '&#x2022; &#x2013;' (BULLET, EN DASH).
Specify which bullet character to use for an <ul>/<li> element. Additional characters are used for nested <li> elements.
For example, if ul-li-bullets="* - +", "*" will be used for <ul>/<li> elements, "-" will be used for <ul>/<li> elements contained in a <ul>/<li> element and "+" will be used for <ul>/<li> elements nested in two <ul>/<li> elements.
Changing the value of this parameter may imply changing the font-family attribute of the attribute-set ul-li-label.
unordered-step-bullets
A string containing one or more single characters separated by whitespace.
Default value: '&#x2022;' (BULLET, EN DASH).
Specify which bullet character to use for a <steps-unordered>/<step> element. Additional characters are used for nested <steps-unordered>/<step> elements.
Changing the value of this parameter may imply changing the font-family attribute of the attribute-set unordered-step-label.
watermark
Allowed values are one or more of 'blank', 'title', 'toc', 'booklist', 'frontmatter', 'body', 'backmatter', 'index', 'all' separated by whitespace.
Default value: 'all'.
Specifies which pages in the output document are to be given a watermark.
By default, all pages are given a watermark. If for example, parameter watermark is set to 'frontmatter body backmatter', then only the pages which are part of the front matter, body and back matter of the output document are given a watermark. The title page, TOC pages, etc, are not given a watermark.
No effect unless parameter watermark-image is specified.
xfc-render-as-table
A string containing zero or more DITA element names separated by whitespace.
Default value: 'note'.
Specifies whether XMLmind XSL-FO Converter Opens in new window should render the <fo:block>s representing specified DITA elements as <fo:table>s.
This parameter enables a workaround for a limitation of XMLmind XSL-FO Converter: a <fo:block> having a border and/or background color and containing several other blocks, lists or tables is very poorly rendered in RTF, WML, DOCX and ODT.

Figure 4-1. Page areas

page_areas.svg

‣ Parent topic: Part I. Using XMLmind DITA Converter

Child topics:

‣ Section 1. Page headers and footers

 (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.
 (3) In linguistic morphology and information retrieval, stemming is the process of reducing inflected (or sometimes derived) words to their word stem, base or root form—generally a written word form.
Previous page Part I, Chapter 3. The ditac command-line utility Part I, Chapter 4. XSLT stylesheets parameters (10 / 32)   Table of Contents   Index Part I, Chapter 4, Section 1. Page headers and footers Next page