Conversa User Guide
Copyright © 2016-2020 Maxprograms
Table of ContentsIntroduction ................................................................................................................................... 1
Conversa DITA Publisher ................................................................................................................ 1Publishing DITA Maps ................................................................................................................... 2
Publish DITA Map Dialog ................................................................................................................ 2Useful Tips ........................................................................................................................................ 3
Conversa Configuration ............................................................................................................... 4Preferences Dialog .......................................................................................................................... 4External Tools ................................................................................................................................... 4XML Catalog ..................................................................................................................................... 5XSL Stylesheet Parameters ............................................................................................................. 5
Common Parameters .............................................................................................................. 6XSL-FO Parameters ................................................................................................................ 13
Page headers and footers ............................................................................................. 22HTML Parameters .................................................................................................................. 26EPUB Parameters ................................................................................................................... 31Help Parameters .................................................................................................................... 32
Common Help Parameters ............................................................................................ 32Web Help Parameters .................................................................................................... 33HTML Help Parameters .................................................................................................. 38Eclipse Help Parameters ................................................................................................ 39
i
Conversa User Guide
Introduction
Conversa DITA PublisherConversa provides a graphical user interface to the free DITA Converter (ditac) from XMLmindthat you can use to easily publish your DITA projects in multiple formats.
Conversa works right out of the box. Just install it and generate PDF, HTML or Web Help from yourDITA files using the default configuration.
The output formats supported by Conversa are:
PostScriptEPUB 2 & 3HTMLPDF
XSL-FOWeb Help with HTML 5Web HelpEclipse Help
ODTDOCXRTFHTML Help
Conversa ships with Apache FOP 2.5 to generate PDF files but you can also use RenderX XEP,Antenna House XSL Formatter or an external Apache FOP if you want customized PDF files.
Microsoft HTML Help Workshop is required to generate HTML Help in .chm format for Windows.It can be freely downloaded from Microsoft's Download Center.
XMLmind XSL-FO Converter is used to generate DOCX, RTF and ODT output from DITA files. XSL-FOConverter is a commercial product from XMLMind.
1Introduction
Conversa User Guide
Publishing DITA Maps
Publish DITA Map Dialog
About this taskSteps for publishing a DITA Map in multiple formats.
Procedure1. In File menu select Publish DITA Map or click the button in the toolbar.
The following dialog appears:
2. Type the name of the DITA map that you want to publish in the DITAMap text box or use theBrowse... button to select a DITA map from the file system.
3. Type the location of the folder where you want the published files to be stored in the OutputFolder text box or click the Browse... button to select a folder from the file system.
4. If you want to use conditional processing when publishing, enter the name of the DITAVALfile in the DITAVAL File text box or click the Browse... button to select the DITAVAL file fromthe file system.
5. Select the desired formats by checking the options in the Output Formats panel.
6. Check the Open Publication Using Default Viewers check box if you want to automaticallyopen the published document right after generating it.
7. Check theOpen Log on Success check box if you want to examine the information generatedby the program even if publication is successful.
8. Click the Publish button to start converting the DITA map to all selected formats.
2Publishing DITA Maps
Conversa User Guide
ResultsAll requested publications are saved in subfolders of the folder indicated Output Folder text box.The names of the subfolders reflect the publication format,
Useful Tips
Adding Bookmarks to PDFSet the pdf-outline parameter to yes in the XSL-FO section of the XSL Parameters tab of thePreferences dialog to add bookmarks in PDF output.
Paper SizeDefault paper size for PDF, RTF, DOCX and ODT is 'A4'. Paper size used in formats that depend onXSL-FO is controlled by the paper-type parameter in the stylesheet for XSL-FO.
Eclipse Help for Multiple PluginsXSL settings can only contain the information of one plugin at a time. Save your current set of XSLparameters using the ExportXSLParametersoption of theXSLParameters tab of thePreferencesdialog after configuring each plugin and load those settings using the Import XSL Parametersbutton before publishing the corresponding Eclipse help.
3Publishing DITA Maps
Conversa User Guide
Conversa Configuration
Preferences DialogConversa default settings can be changed in the Preferences dialog.
• To open the Preferences dialog on Windows or Linux, select Preferences in Settings menu.
• To open the Preferences dialog on Mac OS X, select Preferences in Apple menu.
External Tools
Default XSL-FO Processor for PDFConversa generates XSL-FO files that can be converted to PDF format using the following XSLtransformation engines:
• Built-in Apache FOP 2.5
• External Apache FOP
• Antenna House XSL Formatter
• RenderX XEP
Use the External Tools tab of the Preferences dialog to configure the default XSLT engine.
External ToolsIf you want to generate PDF using XSLT engines other than the built-in Apache FOP, you mustindicate the paths to the XSLT engine executables in the corresponding text boxes. Use theapropriate Browse... button to locate the executables in the file system.
XMLmind XSL-FO converter is required to generate RTF, DOCX or ODT files from a DITA map. Enterthe location of fo2rtf.bat (Windows) or fo2rtf (Mac OS X or Linux) in the XMLmind XSL-FOConverter text box or use the corresponding Browse... button to locate the program in the filesystem.
4Conversa Configuration
Conversa User Guide
Microsoft Help Compiler is required to generate Html Help (Windows help) using conversa. Enterthe location of hhc.exe in the Microsoft Help Compiler text box or use the Browse... button nextto it to select the location from the file system.
XML CatalogThe application includes a default XML catalog with DTDs and XML Schemas for the most relevantformats and supported document types. Additional DTDs and XML Schemas can be added by theuser as needed.
Select the XML Catalog tab in the Preferences dialog to add or remove entries from the catalog.
Add Catalog EntryClick the Add Catalog Entry button and a file selection dialog will appear. Locate the catalog inthe file system and select it.
Remove Catalog EntrySelect the catalog entry to remove in the catalogs table. Click the Remove Catalog Entry buttonand the application's catalog will be updated to reflect the change.
XSL Stylesheet ParametersYou can pass parameters to the XSL stylesheets shipped with Conversa to customize the appearanceof your publications.
Select the XSL Parameters tab in the Preferences dialog to adjust your stylesheets.
5Conversa Configuration
Conversa User Guide
Use the Export XSL Parameters button to save the current set parameters to an XML file and theImport XSL Parameters button to restore a set of customized settings at any time.
The Load Default Values button restores the default values for all parameters in all stylesheets.Use this option if you made a configuration mistake or want to reset all settings at once.
The Show Reference Guide button opens a separate window showing this chapter in a Web Helpversion of this user guide.
Common ParametersThe parameters described below apply to all XSL styleheets used by Conversa.
DescriptionValueParameter
The number format of topics referenced in abookmap as appendix. By default, such topics
Allowed values are:'I', 'i', 'A', 'a', '1'.
appendix-number-format
are numbered as follows: Appendix A. Title ofDefault value: 'A'. first appendix, Appendix B. Title of secondappendix, etc.
In a <troubleshooting> topic, multiple <remedy>elements having no title are given numbersformatted using this format.
Allowed values are:'I', 'i', 'A', 'a', '1'.
Default value: 'A'.
cause-number-format
Specifies which elements are to be centeredhorizontally on the page.
List of element namesseparated bywhitespace.
center
Example: 'figequation-figure
simpletable table'.
Default value: ''.
6Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Text added after the contents of a<equation-number> element.
String.
Default value: ')'.
equation-number-after
Text added before the contents of a<equation-number> element.
String.
Default value: '('.
equation-number-before
Allows to add <frontmatter> and <backmatter>
<topicref>s to the Table of Contents (TOC) ofa document.
Allowed values are:'frontmatter','backmatter', 'both','none'.
extended-toc
Note that the @toc, @navtitle, @locktitle, etc,attributes are applied normally toDefault value: 'none'.<frontmatter> and <backmatter> <topicref>swhen an extended TOC is generated.
Specifies how to resolve <xref> or <link>elements having an external @scope attribute
Allowed values are: '',an URL ending with "/"or '#REMOVE'.
external-resource-base
and a relative @href attribute. Example of such<xref> elements: <xref scope="external"Default value:
'#REMOVE' for EPUB 2 format="java"
href="src/Test.java">Test.java</xref>.and EPUB 3, '' for allthe other outputformats.
''
Do not resolve the @href attribute. Inthis case, the external resource files areexpected to be copied “by hand” to theoutput directory.
An URL ending with "/"This URL is prepended to the value ofthe @href attribute.
'#REMOVE'
The <xref> or <link> element isprocessed as if it did not have an @href
attribute.
Allows to turn off syntax highlighting inelements specializing <pre>.
Allowed values are:'yes' and 'no'.
highlight-source
By default, syntax highlighting is turned on forall elements specializing <pre> and having an
Default value: 'yes'.
@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.
7Conversa Configuration
Conversa User Guide
DescriptionValueParameter
The string used to separate the first pagenumber from the last page number in a page
String.
Default value:'–' (EN DASH).
index-range-separator
range of an indexed term. Example:index-range-separator='<-->':
C
Cat 54, 87<-->90
This parameter specifies which text to generatefor a <link> element, when this <link> element
List of values separatedby whitespace. Allowedvalues are: 'number'and 'text'.
link-auto-text
has no <linktext> child element or when this<linktext> child element is empty.
Default value: 'numbertext'.
Similar to above parameter xref-auto-text butfor <link> elements.
Specifies the type (attribute @type) of the <note>
elements for which icons should be used ratherthan text in order to represent note labels.
List of type attributevalues separated bywhitespace.
note-icon-list
Ignored unless use-note-icon='yes'.Default value:'attention caution
danger fastpath
important note notes
remember restriction
tip'.
Specifies which elements are to be numbered.List of values separatedby whitespace. Allowed
number
'all' is a short form for 'topic table figequation-figure'.
values are: 'topic','chapter-only',
'chapter-only'means: number topics, but onlythose referenced in a bookmap as <part>,<chapter> and <appendix>.
'table', 'fig','example','equation-figure','all'.
NotePlease note that 'all' does notinclude 'example'. If you want to
Default value: ''(number nothing).
number all formal elementsincluding examples, then you mustspecify 'all example'.
The string used to separate the hierarchicalnumber of topics acting as sections.
String.
Default value: '.'.
number-separator1
8Conversa Configuration
Conversa User Guide
DescriptionValueParameter
The string used to separate the hierarchicalnumber of figures, tables, examples andequations.
String.
Default value: '-'.
number-separator2
When possible, the number of figure, table,example or equation is made relative to thenumber of the ancestor chapter or appendix.This gives for example (for descendants ofchapter 5): Figure 5-1. Title of first figure ofchapter 5, Figure 5-2. Title of second figure ofchapter 5, etc.
Generates a "Required" (respectively "Optional")label for <step> and <substep> elements having
Allowed values are:'yes' and 'no'.
mark-important-steps
an @importance attribute set to "required" (resp."optional").
Default value: 'no'.
The number format of topics referenced in abookmap as part. By default, such topics are
Allowed values are:'I', 'i', 'A', 'a', '1'.
part-number-format
numbered as follows: Part I. Title of first part,Part II. Title of second part, etc.Default value: 'I'.
Normally topics which are descendants ofchapters (that is, topics referenced in a
Allowed values are:'yes' and 'no'.
prepend-chapter-to-section-number
bookmap as <chapter>) are numbered asDefault value: 'no'. follows: 1. Title of first section, 1.1. Title of first
subsection, etc.
Specifyingprepend-chapter-to-section-number='yes'
prepends the number of the chapter ancestorto the section number. This gives for example(for descendants of chapter 5): 5.1. Title of firstsection, 5.1.1. Title of first subsection, etc.
In a <troubleshooting> topic, multiple <remedy>elements having no title are given numbersformatted using this format.
Allowed values are:'I', 'i', 'A', 'a', '1'.
Default value: 'A'.
remedy-number-format
Specifies whether <draft-comments> elementsshould be rendered.
Allowed values are:'yes' and 'no'.
show-draft-comments
Default value: 'no'.
In a <troubleshooting> topic, multiple<troubleSolution> elements having no title aregiven numbers formatted using this format.
Allowed values are:'I', 'i', 'A', 'a', '1'.
Default value: '1'.
troubleSolution-number-format
9Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Specifies which elements should have their titlesdisplayed after their bodies.
List of element namesseparated bywhitespace.
title-after
Example: 'figequation-figure
table'.
Default value: ''.
Specifies the kind of ``title page'' (contains thetitle of the document, its author, etc) to be
Allowed values are:'auto', 'none' or the
title-page
generated before the actual contents of thedocument.
URI of a custom titlepage.
'auto'
Automatically generate a title pagebased on the title and metadata of themap.
Default value: 'auto'.
'none'
Do not generate a title page.
URI of a custom title pageSpecifies the URI of a custom title page.If the URI is relative, it is relative to thecurrent working directory of the user.
This custom title page is an XHTML filefor XHTML-based formats (XHTML,HTML Help, etc). This custom title pageis an XSL-FO file for FO-based formats(PDF, RTF, etc). Such custom title pagesare generally hand-written.
• The child nodes of the body
element of the custom XHTML titlepage are wrapped in a div
contained in the XHTML/HTML filebeing generated by the XSLTstylesheet.
Do not add a <!DOCTYPE> to suchcustom XHTML title page becauseotherwise, the XSLT stylesheet mayfail loading it.
See sample custom XHTML titlepage.
• The child nodes of the firstfo:flow[@flow-name='xsl-region-body']
element of the custom XSL-FO titlepage are wrapped in a fo:block
10Conversa Configuration
Conversa User Guide
DescriptionValueParameter
contained the XSL-FO file beinggenerated by the XSLT stylesheet.
See sample custom XSL-FO titlepage.
The string used to separate the number of anformal object from its title.
String.
Default value: '. '.
title-prefix-separator1
Specifies whether icons should be used ratherthan text in order to represent the label of a<note> element.
Allowed values are:'yes' and 'no'.
Default value: 'no'.
use-note-icon
Specifies an image file which is to be used as awatermark in all the pages comprising the
URI. If the URI isrelative, it is relative to
watermark-image
output document. See also parameterwatermark.
the current workingdirectory of the user.
No default value. If you need this feature when generating RTF,WordprocessingML, Office Open XML (.docx),OpenDocument (.odt), please make sure to useXMLmind XSL-FO Converter v5.3+.
This parameter specifies which text to generatefor an <xref> element, when this <xref>
element contains no text at all(1).
List of values separatedby whitespace. Allowedvalues are: 'number'and 'text'.
xref-auto-text
Let's suppose that an <xref> element containingno text at all points to a topic titled"Installation".
Default value:'number'.
Because the <xref> element points to anelement having a <title> child element, ditacmay use this title as a starting point for thegenerated text.
Now let's suppose that topics are numberedand that the number of the "Installation" topicis "Chapter 5".
The text generated for this <xref> element isthus:
If xref-auto-text='number'Chapter 5
If xref-auto-text='text'Installation
(1)This implies that the xref-auto-text parameter is ignored when an <xref> element contains some text.
11Conversa Configuration
Conversa User Guide
DescriptionValueParameter
If xref-auto-text='number text'Chapter 5. Installation
Note that this specification is just a hint becauseditac needs anyway to generate some text. Forexample, if topics are not numbered andxref-auto-text='number', the generated textwill be "Installation".
Most XSLT stylesheets generate files whichreference resources such as icons or CSS
URL. A relative URL isrelative to the outputdirectory.
xsl-resources-directory
stylesheets. This parameter specifies the targetdirectory which is to contain such resources.Default value:
'resources/' resolved If this directory does not exist, it is automaticallycreated.against the directory
which contains theXSLT stylesheets.
If this directory does not already contain theresources needed by the XSLT stylesheets, suchresources are automatically copied to thisdirectory.
The default value of this parameter is somethinglike file:/opt/ditac/xsl/xhtml/resources/
for the stylesheets generating XHTML. URLfile:/opt/ditac/xsl/xhtml/resources/
specifies an existing directory containingbasic.css, note.png, important.png, etc. Thismeans that by default, no directory is createdand no resource is copied.
If the value of this parameter is an absolute URI,then ditac assumes that no resource directoryis to be created and no resource is to be copiedbecause this has already been done by the user.
Important
• Explicitly specifying somethinglikexsl-resources-directory='res'
is almost always required whengenerating files having anXHTML/HTML based format(XHTML, HTML Help, etc).
• Explicitly specifying somethinglikexsl-resources-directory='res'
is almost never required when
12Conversa Configuration
Conversa User Guide
DescriptionValueParameter
generating files converted fromXSL-FO (PDF, RTF, etc).
XSL-FO ParametersThe 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 ofXSL-FO processors such as Apache FOP, RenderX XEP, Antenna House XSL Formatter or XMLmindXSL-FO Converter.
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 theoutput formats which uses XSL-FO as an intermediate format (PDF, RTF, DOCX, etc).
The following table lists the parameters specific to the stylesheets that generate XSL-FO.
DescriptionValueParameter
The size of the ``main font'' of the document. All the otherfont sizes are computed relatively to this font size
Default value:'10pt'.
base-font-size
See Page areas below.Length.body-bottom-margin
Default value:'0.5in'.
Specifies the family of the font used for the text of allelements except topic titles.
A stringcontaining one ormore font families
body-font-family
separated bycommas.
Default value:'serif'.
Applies only to alternate XSLT stylesheetditac_install_dir/xsl/fo/fo_indent.xsl.
Length.
Default value:'2pc'.
body-start-indent
This stylesheet:
• Indents all blocks but topic and section titles by thevalue of XSLT stylesheet parameterbody-start-indent. By default body-start-indent
is 2pc.
13Conversa Configuration
Conversa User Guide
DescriptionValueParameter
• 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 ofits output: manual-fop.pdf.
See Page areas below.Length.body-top-margin
Default value:'0.5in'.
Specify which bullet character to use for a <choice>
element. Additional characters are used for nested<choice> elements.
A stringcontaining one ormore singlecharacters
choice-bullets
Changing the value of this parameter may imply changingthe font-family attribute of the attribute-setchoice-label.
separated bywhitespace.
Default value:'•'
(BULLET).
In a numbered <equation-block> element, this parameterspecifies the width of the column containing the equation.
Length.
Default value:'90%'.
equation-block-equation-width
In a numbered <equation-block> element, this parameterspecifies the width of the column containing the<equation-number> element.
Length.
Default value:'10%'.
equation-block-number-width
Appended after the external URL referenced by an <xref>
or <link> element. Ignored unlessshow-external-links='yes'.
String.
Default value: ']'.
external-href-after
Separates the text of an <xref> or <link> element fromits referenced external URL. Ignored unlessshow-external-links='yes'.
String.
Default value: '['.
external-href-before
Specifies the contents of the central part of a page footer.See Specifying a header or a footer.
String.footer-center
Supports a conditional specification.
Default value:
two-sides even:: {{chapter-title}};;
two-sides part||chapter||appendices||appendix odd::¬
14Conversa Configuration
Conversa User Guide
DescriptionValueParameter
{{section1-title}};;
one-side:: {{chapter-title}}
Specifies the proportional width of the central part of apage footer. See Specifying a header or a footer.
Stringrepresenting an
footer-center-width
integer largerthan or equal to 1. Supports a conditional specification.
Default value: '6'.
See Page areas below.Length.footer-height
Default value:'0.4in'.
Specifies the contents of the left part of a page footer.See Specifying a header or a footer.
String.footer-left
Supports a conditional specification.
Default value:
two-sides even:: {{page-number}}
Specifies the proportional width of the left part of a pagefooter. See Specifying a header or a footer.
Stringrepresenting an
footer-left-width
integer largerthan or equal to 1. Supports a conditional specification.
Default value: '2'.
Specifies the contents of the right part of a page footer.See Specifying a header or a footer.
String.footer-right
Supports a conditional specification.
Default value:
two-sides first||odd:: {{page-number}};;
one-side:: {{page-number}}
Specifies the proportional width of the right part of a pagefooter. See Specifying a header or a footer.
Stringrepresenting an
footer-right-width
integer largerthan or equal to 1. Supports a conditional specification.
Default value: '2'.
Specifies whether an horizontal rule should be drawnabove the page footer.
Allowed valuesare: 'yes' and'no'.
Default value:'yes'.
footer-separator
15Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Specifies the contents of the central part of a page header.See Specifying a header or a footer.
String.
Default value:'{{document-title}}'.
header-center
Supports a conditional specification.
Specifies the proportional width of the central part of apage header. See Specifying a header or a footer.
Stringrepresenting an
header-center-width
integer largerthan or equal to 1. Supports a conditional specification.
Default value: '6'.
See Page areas below.Length.header-height
Default value:'0.4in'.
Specifies the contents of the left part of a page header.See Specifying a header or a footer.
String.
Default value: ''.
header-left
Supports a conditional specification.
Specifies the proportional width of the left part of a pageheader. See Specifying a header or a footer.
Stringrepresenting an
header-left-width
integer largerthan or equal to 1. Supports a conditional specification.
Default value: '2'.
Specifies the contents of the right part of a page header.See Specifying a header or a footer.
String.
Default value: ''.
header-right
Supports a conditional specification.
Specifies the proportional width of the right part of a pageheader. See Specifying a header or a footer.
Stringrepresenting an
header-right-width
integer largerthan or equal to 1. Supports a conditional specification.
Default value: '2'.
Specifies whether an horizontal rule should be drawnbelow the page header.
Allowed valuesare: 'yes' and'no'.
Default value:'yes'.
header-separator
Specifies whether words may be hyphenated.Allowed valuesare: 'yes' and'no'.
hyphenate
16Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Default value:'no'.
The number of columns of index pages.Positive integer.index-column-count
Default value: '2'.
The distance which separates columns in index pages.Length.index-column-gap
Default value:'2em'.
Specifies whether text (e.g. in paragraphs) should bejustified (that is, flush left and right) or just left aligned(that is, flush left and ragged right).
Allowed valuesare: 'yes' and'no'.
justified
Default value:'no'.
Specify which character is inserted before the text of a<link> element.
A stringcontaining asingle character.
link-bullet
Changing the value of this parameter may imply changingthe font-family attribute of the attribute-setlink-bullet.
Default value:'•'
(BULLET).
Specify which character is used to separate the childelements of a <menucascade> element.
A stringcontaining asingle character.
menucascade-separator
Changing the value of this parameter may imply changingthe font-family attribute of the attribute-setmenucascade-separator.
Default value:'→'
(RIGHTWARDSARROW).
The height of a note icon.Length. A lengthmay have a unit.Default is px.
note-icon-height
Default value:'32'. '7mm' forthe XSLTstylesheets thatgenerate XSL-FO.
The suffix of a note icon.Default value:'.png'.
note-icon-suffix
The root name of a note icon should be identical to thevalue of the @type attribute it represents. For example, ifnote-icon-suffix='.svg', the default resources directory
17Conversa Configuration
Conversa User Guide
DescriptionValueParameter
is expected to contain note.svg, important.svg,caution.svg, etc.
In principle, there is no need for an end-user to specifyany of the note-icon-suffix, note-icon-width ornote-icon-height parameters.
The width of a note icon.Length. A lengthmay have a unit.Default is px.
note-icon-width
Default value:'32'. '7mm' forthe XSLTstylesheets thatgenerate XSL-FO.
See Page areas below.Length.page-bottom-margin
Default value:'0.5in'.
The height of the printed page.Length. Example:'297mm'.
page-height
Default value:depends onpaper-type.
See Page areas below.Length.page-inner-margin
Default value: ifparametertwo-sided isspecified as 'yes'then '1.25in'
otherwise '1in'.
The orientation of the printed page.Allowed valuesare: 'portrait'and 'landscape'.
page-orientation
Default value:'portrait'.
See Page areas below.Length.page-outer-margin
Default value: ifparametertwo-sided isspecified as 'yes'
18Conversa Configuration
Conversa User Guide
DescriptionValueParameter
then '0.75in'
otherwise '1in'.
Appended after the page number pointed to by an <xref>
or <link> element. Ignored unless show-xref-page='yes'or show-link-page='yes'.
String.
Default value: ''.
page-ref-after
When both page-ref-after and page-ref-before arespecified as the empty string, in fact, this specifies thatthe generated string must be the localized equivalent of"on page".
Separates the text of an <xref> or <link> element fromthe page number it points to. Ignored unlessshow-xref-page='yes' or show-link-page='yes'.
String.
Default value: ''.
page-ref-before
See Page areas below.Length.page-top-margin
Default value:'0.5in'.
The width of the printed page.Length. Example:'8.5in'.
page-width
Default value:depends onpaper-type.
A convenient way to specify the size of the printed page.Allowed valuesare: 'Letter',
paper-type
It is also possible to specify a custom paper type byignoring the paper-type parameter and directly specifyingthe page-width and page-height parameters.
'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'.
19Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Specifies whether PDF bookmarks should be generated.Allowed valuesare: 'yes' and'no'.
pdf-outline
Supported by the 'XEP' , 'FOP' and 'AHF' XSL-FOprocessors. Not relevant, and thus ignored by 'XFC'.
Default value:'no'.
Specifies whether the external URL referenced by an<xref> or <link> element should be displayed right afterthe text contained by this element.
Allowed valuesare: 'yes' and'no'.
show-external-links
Example: show-external-links='yes'causes <xrefhref="http://www.oasis-open.org/">Oasis</xref> to
Default value:'no'.
be rendered as follows:Oasis [http://www.oasis-open.org/].
Specifies whether a numbered list should be generatedfor an <imagemap> element, with one list item per <area>element.
Allowed valuesare: 'yes' and'no'.
show-imagemap-links
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).
Default value:'yes'.
Same as show-xref-page but for <link> elements.Allowed valuesare: 'yes' and'no'.
show-link-page
Default value:'no'.
Specifies whether the page number corresponding to theinternal link target referenced by an <xref> element shouldbe displayed right after the text contained by this element.
Allowed valuesare: 'yes' and'no'.
show-xref-page
Example: show-xref-page='yes'causes <xrefhref="introduction.dita">Introduction</xref> to berendered as follows: Introduction [3].
Default value:'no'.
Specifies the color used for the text of topic (of any kind)titles.
A stringrepresenting acolor.
title-color
Default value:'black'.
Specifies the family of the font used for the text of topic(of any kind) titles.
A stringcontaining one ormore font families
title-font-family
separated bycommas.
20Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Default value:'sans-serif'.
Specifies whether the document should be printed doublesided.
Allowed valuesare: 'yes' and'no'.
two-sided
Default value:'no'.
Specify which bullet character to use for an <ul>/<li>element. Additional characters are used for nested <li>
elements.
A stringcontaining one ormore singlecharacters
ul-li-bullets
For example, if ul-li-bullets="* - +", "*"will be usedfor <ul>/<li> elements, "-" will be used for <ul>/<li>
separated bywhitespace.
elements contained in a <ul>/<li> element and "+" willDefault value:'•
be used for <ul>/<li> elements nested in two <ul>/<li>elements.
–'
Changing the value of this parameter may imply changingthe font-family attribute of the attribute-setul-li-label.
(BULLET,EN DASH).
Specify which bullet character to use for a<steps-unordered>/<step>element. Additional charactersare used for nested <steps-unordered>/<step> elements.
A stringcontaining one ormore singlecharacters
unordered-step-bullets
Changing the value of this parameter may imply changingthe font-family attribute of the attribute-setunordered-step-label.
separated bywhitespace.
Default value:'•'
(BULLET,
EN DASH).
Specifies which pages in the output document are to begiven a watermark.
Allowed valuesare one or more
watermark
of 'blank', By default, all pages are given a watermark. If for example,parameter watermark is set to 'frontmatter body
'title', 'toc','booklist',
backmatter', then only the pages which are part of the'frontmatter', front matter, body and back matter of the output'body', document are given a watermark. The title page, TOC
pages, etc, are not given a watermark.'backmatter','index', 'all'
No effect unless parameter watermark-image is specified.separated bywhitespace.
Default value:'all'.
21Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Specifies whether XMLmind XSL-FO Converter shouldrender the <fo:block>s representing specified DITAelements as <fo:table>s.
A stringcontaining zero ormore DITAelement names
xfc-render-as-table
This parameter enables a workaround for a limitation ofXMLmind XSL-FO Converter: a <fo:block>having a border
separated bywhitespace.
and/or background color and containing several otherDefault value:'note'.
blocks, lists or tables is very poorly rendered in RTF, WML,DOCX and ODT.
Page areas
Page headers and footers
Specifying a header or a footerThe header or the footer of a generated PDF, RTF, etc, page has 3 columns.
22Conversa Configuration
Conversa User Guide
Layout of a header
The width of these columns may be specified using the header-left-width, header-center-width,header-right-widthparameters for the header and the footer-left-width, footer-center-width,footer-right-width parameters for the footer.
The width of a column is specified as an integer which is larger than or equal to 1. This value isthe proportional width of the column. For example, if the left column has a width equal to 2 and theright column has a width equal to 4, this simply means that the right column is twice (4/2 = 2) aswide as the left column.
The contents of these columns may be specified using the header-left, header-center,header-right parameters for the header and the footer-left, footer-center, footer-rightparameters for the footer.
When header-left, header-center, header-right are all specified as the empty string, no headeris generated. When footer-left, footer-center, footer-right are all specified as the emptystring, no footer is generated.
The content of a column is basically a mix of text and variables. Example: "Page {{page-number}}of {{page-count}}".
Supported variables are:
{{document-title}}
The title of the document.
{{document-date}}
The publication date of the document.
The value of the variable comes from the last created or revised element found in thetopicmeta/critdatesor bookmeta/critdates element of the map. More precisely, it comesthe value of attribute golive, modified or date, considered in that order. The value ofthis attribute must be something like YYYY-MM-DD, because it is parsed and then formattedaccording to the xml:lang of the map. For example, if golive="2014-02-23", withxml:lang="en", it gives: "February 02, 2014" and with xml:lang="fr", it gives: "02Février 2014". If the map has no critdates element, then the current date is used. Ifthe value of attribute golive, modified or date is not specified as YYYY-MM-DD, then thisvalue is used as is.
{{chapter-title}}
The title of the current part, chapter, appendices or appendix . Empty if the map beingconverted is not a bookmap.
{{section1-title}}
The title of the current part, chapter, appendices or appendix or section 1 . A section 1 isspecified by a non-typed topicref (that is, not a part, chapter, preface, appendix,dedication, etc) which is a direct child of a map or bookmap.
23Conversa Configuration
Conversa User Guide
{{topic-title}}
The title of the current topic. All topics are guaranteed to have a corresponding{{topic-title}}. Even automatically generated topics such as toc or indexlist have a
corresponding {{topic-title}}(2).
{{page-number}}
Current page number within the current document division (front matter, body matteror back matter) .
{{page-count}}
Total number of pages of the current document division (front matter, body matter orback matter).
{{break}}
A line break.
{{image(URI)}}
An image having specified URI. A relative URI is resolved against the current workingdirectory. Example: "{{image(artwork/logo.svg)}}".
{{page-sequence}}
Not for production use. Inserts in the header/footer the name of the current page sequence. This allows to learn which name to use in a conditional header or footer. See below.
Conditional headers and footersThe default value of header-center is '{{document-title}}'. This means that each page of thegenerated PDF, RTF, etc, file will have the document title centered on its top. But what if you wantthe pages containing the Table of Contents have a "Contents" header? Is there a way to specify:use "Contents" for the pages containing the Table of Contents and use the title of the documentfor any other page?
This is done by specifying the following conditional value for parameter header-center: 'toc::Contents;; {{document-title}}'.
A conditional value may contain one or more cases separated by ";;". Each case is tested againstthe page being generated. The first case which matches the page being generated is the onewhich is selected.
conditional_value --> case [ ";;" case ]*
case --> [ condition "::" ]* value
condition --> [ test_page_sequence ]?& [ S test_page_layout ]?& [ S test_page_side ]?
Let's suppose you also want the the pages containing the Index have a "Index" header. Specifying'toc:: Contents;; {{document-title}};; indexList:: Index'won't work as expected becausethe second case (having no condition at all) matches any page, including the Index pages. Youneed to specify: 'toc:: Contents;; indexlist:: Index;; {{document-title}}'.
(2)The {{topic-title}} of a toc is "Table of Contents", properly localized. The {{topic-title}} of aindexlist is "Index", properly localized.
24Conversa Configuration
Conversa User Guide
Let's remember that variable {{topic-title}} is substituted with the title of the current topic,including automatically generated topics such toc and indexlist.
Therefore our conditional value is better expressed as: 'toc:: indexlist:: {{topic-title}};;{{document-title}}'. Notice how a case may have several conditions. Suffice for any of theseconditions to match the page being generated for the case to be selected.
Even better, specify 'toc||indexlist:: {{topic-title}};; {{document-title}}'. String "||"may be used to separate alternative values to be tested against the page being generated.
test_page_sequence --> page_sequence [ "||" page_sequence ]*
page_sequence --> "abbrevlist" | "amendments" | "appendices" | "appendix"| "backmattersection" | "bibliolist" | "bookabstract" | "booklist"| "chapter" | "colophon" | "dedication" | "draftintro"| "figurelist" | "glossarylist" | "indexlist" | "notices"| "part" | "preface" | "section1" | "tablelist"| "toc" | "trademarklist"
Tip
It's not difficult to guess that the name of the page sequence corresponding to the Tableof Contents is toc and that the name of the page sequence corresponding to the Index isindexlist. However the simplest way to learn what is the name of the page sequence beinggenerated is to reference variable {{page-sequence}} in the specification of a header or afooter.
Now let's suppose that we want to suppress the document title on the first page of a part, chapteror appendix. This is specified as follows: 'first part||chapter||appendix:: ;; toc||indexlist::{{topic-title}};; {{document-title}}'.
For now, we have only described a condition about the page sequence being generated: TOC,Index, etc. In fact, a condition may test up to 3 facets of the page being generated:
• The page sequence to which belongs the page being generated.• Whether the page being generated is part of a one-sided or a two-sided document.• Whether the page being generated is the first page of its sequence. When the the page being
generated is not the first page of its sequence, if the page being generated has an odd or aneven page number.
test_page_layout --> page_layout [ "||" page_layout ]*
page_layout --> "two-sides" | "one-side"
test_page_side --> page_side [ "||" page_side ]*
page_side --> "first" | "odd" | "even"
25Conversa Configuration
Conversa User Guide
Remember
When the document has one side, there is no difference between even and odd. That is,even, odd, even||odd all simply mean: other than first.
The order of the tests is not significant. For example, 'first part||chapter||appendix' isequivalent to 'part||chapter||appendix first'.
Therefore 'first part||chapter||appendix:: ;; toc||indexlist:: {{topic-title}};;
{{document-title}}' reads as follows:
1. Use the empty string for the first page of a part, chapter or appendix.2. Use the topic title for the pages containing the Table of Contents. This title is "Table of
Contents", but localized according to the main language of the DITA document beingconverted.
3. Use the topic title for the pages containing the Index. This title is "Index", but localizedaccording to the main language of the DITA document being converted.
4. For any other page, use the title of the DITA document.
NoteEverything explained in this section applies not only to the contents of a column of a headeror footer, but also to the proportional width of a column of a header or footer. Example:-p footer-right-width "first||odd:: 4;; even:: 1".
HTML ParametersThe following table lists the parameters that are common to the stylesheets that generate XHTMLor HTML. They apply to the stylesheets that produce XHTML, HTML, Web Help and HTML Help,Eclipse Help and EPUB.
DescriptionValueParameter
Specifies whether an A-Z list should be addedat the beginning of the back-of-the-book index.
Allowed values are:'yes' and 'no'.
add-index-toc
Default value: 'yes'.
Specifies whether a header and/or a footercontaining navigation icons should be generatedin order to link together all the HTML pages.
Allowed values are:'none', 'top','bottom' or 'both'.
chain-pages
NoteThere is no need to specify a valueother than 'none'when generating
Default value: 'none'.
Web Help, HTML Help, Eclipse Help,EPUB and Java™ Help.
26Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Specifies whether navigation icons should begenerated in order to link together all the topics.
Allowed values are:'yes' and 'no'.
chain-topics
See also related parameter:ignore-navigation-links.
Default value: 'no'.
NoteThere is no need to specify a valueother than 'no' when generatingWeb Help, HTML Help, Eclipse Help,EPUB and Java™ Help.
Low-level parameter specifying which CSSstylesheet to use to style the generated (X)HTMLpages.
URL.
Default value: ''.
css
When neither css nor custom-css is specified,the default CSS stylesheet being used isxsl-resources-directory/base.css.
Restriction
Not supported by the stylesheetsthat generate EPUB.
Very low-level parameter specifying which CSSstylesheet to use. This CSS stylesheet is expectedto be found in the resources directory.
URL basename relativeto the directoryspecified by parameterxsl-resources-directory.
cssResourceName
Note
This parameter is not useful unlessyou develop a plug-in implementing
Default value:'base.css'.
a DITA specialization. Moreinformation inhttps://www.xmlmind.com/ditac/_distrib/doc/manual/webhelp/specialize.html.
Specifies the custom CSS stylesheet used to stylethe generated (X)HTML pages. This high-level
URL.
Default value: ''.
custom-css
parameter has priority over low-level parametercss.
27Conversa Configuration
Conversa User Guide
DescriptionValueParameter
This custom CSS stylesheet is copied to directoryxsl-resources-directory. Thereforecustom-css requires directoryxsl-resources-directory to be specified as anURL which is relative to the output directory(e.g. xsl-resources-directory='res').
How to use custom-css is explained inhttps://www.xmlmind.com/ditac/_distrib/doc/manual/webhelp/manual-6.html#customCSS.
The default width of <table> and <simpletable>
elements.A percentage, typicallysomething like '100%'
or '90%'.
default-table-width
Default value: '' (asnarrow as possible).
The height of the “opens in new window” icon.Length. A length mayhave a unit. Default ispx.
external-link-icon-height
Default value: '10'.
The basename of the “opens in new window”icon. This icon is found in the resourcesdirectory.
Basename.
Default value:'new_window.png'.
external-link-icon-name
The width of the “opens in new window”' icon.Length. A length mayhave a unit. Default ispx.
external-link-icon-width
Default value: '10'.
Allows to map DITA xref/@format to XHTMLa/@type.
Zero or more DITAformat/MIME typepairs. Example:
format-to-type
Using default empty value, <xrefscope="external" format="txt"
"txt text/plainxml application/xml
html text/html". href="http://acme.com/info.xyz"> isconverted to <a
Default value: '',which means that DITA
href="http://acme.com/info.xyz"
target="_blank">. The fact that file extensionxref/@format is not ".xyz" is unknown may cause problems whenconverted to XHTMLa/@type.
attempting to navigate or download file"info.xyz" using a Web browser.
If -p format-to-type "txt text/plain" ispassed to ditac then <xref scope="external"
format="txt"
href="http://acme.com/info.xyz"> is
28Conversa Configuration
Conversa User Guide
DescriptionValueParameter
converted to <a type="text/plain"
href="http://acme.com/info.xyz"
target="_blank">, which is better.
The name of the software which has been usedto create the HTML pages.
String
Default value: 'XMLmindDITA Converter
VERSION'.
generator-info
Specify an empty string if you don't want to havea <meta name="generator" content="XXX"/>
element added to your HTML pages.
If 'yes', do not generate the navigation linkscorresponding to topicref attribute@collection-type.
Allowed values are:'yes', 'no' and 'auto'.
Default value: 'auto'for XHTML and its
ignore-navigation-links
If 'no', generate the navigation linkscorresponding to topicref attribute@collection-type.
variants; 'yes' for WebHelp, Java Help, HTMLHelp, Eclipse Help andEPUB If 'auto', generate the navigation links
corresponding to topicref attribute@collection-type, unless chain-topics=yes.
The URLs specified in this parameter must pointto JavaScript files. These URLs are converted to
String. List of URLsseparated bywhitespace.
javascripts
<script> XHTML elements added to the<html>/<head> elements of the XHTML filesgenerated by ditac.
Default value: ''.
Note that an URL may end with ';async',';defer' or a combination of both flags. Theseflags are translated to the correspondingattributes of the <script> element. Example:
https://cdn.mathjax.org/mathjax/latest/¬
MathJax.js?config=MML_CHTML;async
is translated to:
<script type="text/javascript" async="async"
src="https://cdn.mathjax.org/mathjax/latest/¬
MathJax.js?config=MML_CHTML">
</script>
Very few web browsers (Firefox) can nativelyrender MathML. Fortunately, there is MathJax.
Allowed values are:'yes', 'no' and'auto'.
mathjax
MathJax is a JavaScript display engine formathematics that works in all browsers.
Default value: 'no'.'yes'
Add a <script> XHTML elementloading MathJax to the <html>/<head>
29Conversa Configuration
Conversa User Guide
DescriptionValueParameter
elements of all XHTML files generatedby ditac.
'auto'
Same as 'yes', but add <script> onlyto generated XHTML files containingMathML.
Ignored by all XHTML-based formats but XHTMLand Web Help.
The URL allowing to load the MathJax engineconfigured for rendering MathML.
String.
Default value: the URLpointing to the MathJax
mathjax-url
Ignored unless parameter mathjax is set to'yes'or 'auto'.CDN, as recommended
in the MathJaxdocumentation.
Specifies whether an external link should bemarked using a “opens in new window” icon.
Allowed values are:'yes' and 'no'.
mark-external-links
Default value: 'no'.
The height of a navigation icon.Length. A length mayhave a unit. Default ispx.
navigation-icon-height
Default value: '16'.
The suffix of a navigation icon.String.navigation-icon-suffix
The root names of navigation icons are fixed:
first, first_disabled,
Default value: '.png'.
last, last_disabled,next, next_disabled,previous, previous_disabled,parent, parent_disabled,child, child_disabled.
For example, if note-icon-suffix='.svg', thedefault resources directory is expected tocontain first.svg, first_disabled.svg,last.svg, etc.
In principle, there is no need for an end-user tospecify any of the navigation-icon-suffix,navigation-icon-width ornavigation-icon-height parameters.
30Conversa Configuration
Conversa User Guide
DescriptionValueParameter
The width of a navigation icon.Length. A length mayhave a unit. Default ispx.
navigation-icon-width
Default value: '16'.
The resolution of the screen in dot per inch(DPI). This resolution is used to convert imagedimensions such as 3cm to pixels.
Positive integer.
Default value: '96'.
screen-resolution
Low-level parameter. Do not change defaultvalue unless you know what you are doing.
A MIME type without aparameter such as
xhtml-mime-type
'text/html', • Specify 'text/html' to serve XHTML asHTML.
This is the default value for all(X)HTML-based output formats except forEPUB 2 and (X)HTML5.
'application/xhtml+xml','application/xml' orthe empty string ('').
Default value: seeprose.
• Specify 'application/xhtml+xml' if youprefer to serve XHTML as XML.
This is the default value for EPUB 2.
• Specify an empty string if you prefer not togenerate<meta http-equiv="Content-Type">.
This is the default value for (X)HTML5 forwhich a <meta charset="UTF-8"> isgenerated instead.
EPUB ParametersThe following table lists the parameters specific to the stylesheets that generate EPUB.
DescriptionValueParameter
Specifies an image file which is to be used asthe cover page of the EPUB file. This image must
URI. If the URI isrelative, it is relative to
cover-image
be a PNG or JPEG image. Its size must notexceed 1000x1000 pixels.
the current workingdirectory of the user.
In theory, EPUB 3 also accepts SVG 1.1 coverimages.
No default value.
A globally unique identifier for the generatedEPUB document (typically the permanent URLof the EPUB document).
String
Default value:dynamically generatedUUID URN.
epub-identifier
31Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Only applies to EPUB 3.Allowed values are:'yes' and 'no'.
epub2-compatible
By default, the EPUB 3 files generated by ditacare made compatible with EPUB 2 readers.Specify 'no' if you don't need this compatibility.
Default value: 'yes'.
Only applies to EPUB 3.Allowed values are:'yes' and 'no'.
generate-epub-trigger
Specify 'no' if your EPUB 3 reader does notsupport epub:trigger yet. WhenDefault value: 'yes'.generate-epub-trigger=no, ditac generates an@onclick attribute containing simple JavaScriptcode and declares the containing XHTML 5 pageas being scripted.
Help ParametersTo access the configuration options for Web Help, HTML Help and Eclipse help, select the HelpSystems option in the XSL Parameters tab of the Preferences dialog.
Common Help Parameters
Parameters common to the stylesheets that generate Web Help, HTML Help, Eclipse Help andEPUB
DescriptionValueParameter
If 'yes', add a pseudo TOC entry, bearing thetitle of the document, containing all the actualTOC entries.
Allowed values are:'yes' and 'no'.
Default value: 'yes'.
add-toc-root
32Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Restriction
• Value 'no' is not supported bythe stylesheets that generateEclipse Help.
• Ignored by the stylesheets thatgenerate Web Help and EPUB.
If 'yes', number the TOC entries. No effectunless the number parameter is used to specifythat topics should be numbered.
Allowed values are:'yes' and 'no'.
Default value: 'yes' forWeb Help, 'no' for theother formats.
number-toc-entries
Web Help Parameters
The table below lists the parameters specific to the stylesheets that generate Web Help.
Parameters marked using this icon are pseudo-parameters. They may or may not be passed tothe XSLT stylesheets, but it is important thing to remember that they are also interpreted by ditacitself. As a consequence, you cannot specify them in an XSLT stylesheet which customizes the stockones.
DescriptionValueParameter
This kind of parameter may be used to overrideany of the default values of the CSS variables
String. A valid CSSproperty value.
wh---CSS_VAR_NAME
specified in any of the NNtheme.css templateNo default.files (all found inditac_install_dir/whc_template/_wh/).
For example, the main NNtheme.css templatefile:
body {
...
--navigation-width: 33%;
...
}
The wh---navigation-widthCSS variable is usedas follows in NNcommon.css, another CSStemplate file:
#wh-navigation {
...
width: var(--navigation-width);
33Conversa Configuration
Conversa User Guide
DescriptionValueParameter
...
}
Therefore parameter wh---navigation-widthmay be used to give the navigation side of thegenerated Web Help a different initial width.Example: -p wh---navigation-width "25%".
More examples in "XMLmind Web Help CompilerManual, Getting started".
Specifies whether the TOC should be initiallycollapsed.
Allowed values are:'yes' and 'no'.
wh-collapse-toc
Default value: 'no'.
Specifies whether words looking like numbersare to be indexed.
Allowed values are:'yes' and 'no'.
wh-index-numbers
Examples of such number-like words: 3.14, 3,14,3times4equals12, +1, -1.0, 3px, 1,2cm, 100%,1.0E+6, 1,000.00$.
Default value: 'no'.
When wh-inherit-font-and-colors is set to'no', the navigation pane of the generated Web
Allowed values are:'yes' and 'no'.
wh-inherit-font-and-colors
Help uses fonts and colors of its own, which willDefault value: 'yes'.generally differ from those used for the contentof the Web Help.
Setting wh-inherit-font-and-colors to 'yes'
lets you use for the navigation pane the samefonts and colors as those used for the contentof 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.
Specifies the location of the JavaScript filecontaining jQuery . Example:
Relative or absoluteURI. A relative URI is
wh-jquery
relative to the URI of apage of the Web Help. https://code.jquery.com/¬
jquery-3.4.1.slim.min.jsDefault value: absoluteURI of the Specifying an "https:" URL is recommended
when the generated Web Help is stored on anHTTPS server.
corresponding file
34Conversa Configuration
Conversa User Guide
DescriptionValueParameter
found on the GoogleCDN.
Specifies whether all jQuery files should becopied to _wh/jquery/, where _wh/ is thedirectory containing the other Web Help files.
Allowed values are:'yes' and 'no'.
Default value: 'no'.
wh-local-jquery
By default, the jQuery files are accessed fromthe Web (typically from a CDN).
Note that this parameter is applied after jQueryhas been possibly customized using parameterwh-jquery. For example,"-p wh-jquery https://code.jquery.com/jquery-3.4.1.js"copies a file downloaded fromhttps://code.jquery.com/ to _wh/jquery/.
Selects a layout for the generated Web Help.The name of a layout.wh-layout
For now, only two layouts are supported:classic and simple.
Default value: classic.
Specifies whether the generated Web Helpshould be “responsive”, that is, whether it shouldadapt its layout to the size of the screen.
Allowed values are:'yes' and 'no'.
Default value: 'yes'.
wh-responsive-ui
Specifies which language should be used forthe messages (tab labels, button tool tips, etc)of the generated Web Help.
"browser" or"document" or alanguage code
wh-ui-language
conforming RFC 3066.Examples: de, fr-CA.
Default value "browser" means that thislanguage is the one used by the Web browserfor its own messages. This language may oftenDefault value:
'browser'. be specified in the user preferences of the Webbrowser.
Value "document" means that the language ofthe document should be used.
A language code such as en, en-US, es, es-AR,etc, may be used to explicitly specify whichlanguage should be used.
Specifies whether stemming(3) should be usedto implement the search facility. By default,stemming is used whenever possible, that is,
Allowed values are:'yes' and 'no'.
Default value: 'yes'.
wh-use-stemming
(3)In linguistic morphology and information retrieval, stemming is the process of reducing inflected (orsometimes derived) words to their word stem, base or root form—generally a written word form.
35Conversa Configuration
Conversa User Guide
DescriptionValueParameter
1. when the main language of the documentcan 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 specifiedby the @xml:lang attribute found on the rootelement of DITA map being converted;otherwise using the -lang command-line option;otherwise, it is assumed to be "en".
Specifies the user's CSS stylesheet which is tobe added to each page of the Web Help.
Filename or absoluteURI of a CSS file. A
wh-user-css
relative filename is This file is copied tooutput_directory/_wh/user/.relative to the current
working directory.Sample user's CSSwh_resources/header_footer.css as used in thefollowing 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
Specifies the user's footer which is to be addedto each page of the Web Help.
Filename or absoluteURI of an XHTML file. A
wh-user-footer
relative filename is The content of the <body> element ofwh-user-footer is inserted as is in the
relative to the currentworking directory.
<div id="wh-footer"> found in each page ofthe Web Help.
Same remark as for parameter wh-user-headerabout the resources referenced by a user'sfooter.
Sample user's footer wh_resources/footer.htmlas used in the following example:
-p wh-user-header¬
wh_resources/header.html
-p wh-user-footer¬
wh_resources/footer.html
36Conversa Configuration
Conversa User Guide
DescriptionValueParameter
-p wh-user-css¬
wh_resources/header_footer.css
-p wh-user-resources¬
wh_resources/header_footer_files
More examples in "XMLmind Web Help CompilerManual, Getting started".
Specifies the user's header which is to be addedto each page of the Web Help.
Filename or absoluteURI of an XHTML file. A
wh-user-header
relative filename is The content of the <body> element ofwh-user-header is inserted as is in the
relative to the currentworking directory.
<div id="wh-header"> found in each page ofthe Web Help.
If a user's header references resources (e.g.image files), then these resources must eitherbe referenced using absolute URLs or theseresources must be found in a user's resourcedirectory and parameter wh-user-resourcesmust be specified.
Example:
• The user's resource directory is calledheader_footer_files/ and containsheader_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 referencelogo200x100.png.
Sample user's headerwh_resources/header.html as used in thefollowing example:
37Conversa Configuration
Conversa User Guide
DescriptionValueParameter
-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 CompilerManual, Getting started".
Specifies a user's resource directory which is tobe recursively copied tooutput_directory/_wh/user/.
Filename or absolute"file:" URI of adirectory. URI schemes
wh-user-resources
other than "file" (e.g. This directory typically contains image filesreferenced by the user's header, footer or CSSstylesheet.
"http") are notsupported for thisparameter. A relative
Sample user's resource directorywh_resources/header_footer_files/ as used inthe following example:
filename is relative tothe current workingdirectory.
-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 CompilerManual, Getting started".
Basename of the Index XML input file ofXMLmind Web Help Compiler.
URL basename.
Default value:'whc_index.xml'.
whc-index-basename
In principle, there is no need for an end-user tospecify this parameter.
Basename of the TOC XML input file of XMLmindWeb Help Compiler.
URL basename.
Default value:'whc_toc.xml'.
whc-toc-basename
In principle, there is no need for an end-user tospecify this parameter.
HTML Help Parameters
The following table lists the parameters specific to the stylesheets that generate HTML Help.
38Conversa Configuration
Conversa User Guide
Notice that there should be no need no need for an end-user to specify any of these parameters.
DescriptionValueParameter
Basename of the HTML Help contents file.URL basename.hhc-basename
Default value:'toc.hhc'.
URL of the file containing the template of theHTML Help project file. This plain text file
URL basename.
Default value:'template.hhp'
hhp-template
encoded in UTF-8 contains variables such as%compiledFile%, %contentsFile%,
resolved against the%defaultTopic%, etc, which are substituted withtheir values.
directory whichcontains the XSLTstylesheets.
Basename of the HTML Help index file.URL basename.hhx-basename
Default value:'index.hhx'.
Eclipse Help Parameters
The following table lists the parameters specific to the stylesheets that generate Eclipse Help
DescriptionValueParameter
An ID uniquely identifying the plug-in, typicallya Java-like fully qualified name. Example:'com.acme.widget.userguide'.
String
No default value.
plugin-id
Important
The subdirectory of plugins/containing the plug-in must havethe same basename as the value ofparameter plugin-id.
Basename of the index file.URL basename.plugin-index-basename
Default value:'index.xml'.
The name of the plug-in, typically the title of thedocument. Example: 'ACME Widget User'sGuide'.
String
No default value.
plugin-name
The author, company or organization which hascontributed the plug-in. Example: 'ACME Corp.'.
String
No default value.
plugin-provider
39Conversa Configuration
Conversa User Guide
DescriptionValueParameter
Basename of the table of contents file.URL basename.plugin-toc-basename
Default value:'toc.xml'.
The version of the plug-in.Stringplugin-version
Default value: '1.0.0'.
40Conversa Configuration
Conversa User Guide
Index
Aadd-index-toc, parameter, 26add-toc-root, parameter, 32appendix-number-format, parameter, 6
Bbase-font-size, parameter, 13body-bottom-margin, parameter, 13body-font-family, parameter, 13body-start-indent, parameter, 13body-top-margin, parameter, 14{{break}}, page header/footer variable, 24
Ccause-number-format, parameter, 6center, parameter, 6chain-pages, parameter, 26chain-topics, parameter, 27. See alsoignore-navigation-links, parameter{{chapter-title}}, page header/footer variable,23choice-bullets, parameter, 14cover-image, parameter, 31css, parameter, 27cssResourceName, parameter, 27custom-css, parameter, 27
Ddefault-table-width, parameter, 28{{document-date}}, page header/footervariable, 23{{document-title}}, page header/footervariable, 23.docx, filename extension, 11. See also OfficeOpen XML, output format
EEPUB 2, output format, 7epub2-compatible, parameter, 32EPUB 3, output format, 7, 31, 32epub-identifier, parameter, 31equation-block-equation-width, parameter, 14equation-block-number-width, parameter, 14equation-number-after, parameter, 7equation-number-before, parameter, 7extended-toc, parameter, 7
external-href-after, parameter, 14external-href-before, parameter, 14external-link-icon-height, parameter, 28external-link-icon-name, parameter, 28external-link-icon-width, parameter, 28external-resource-base, parameter, 7
Ffooter-center, parameter, 14footer-center-width, parameter, 15footer-height, parameter, 15footer-left, parameter, 15footer-left-width, parameter, 15footer-right, parameter, 15footer-right-width, parameter, 15footer-separator, parameter, 15format-to-type, parameter, 28
Ggenerate-epub-trigger, parameter, 32generator-info, parameter, 29
Hheader-center, parameter, 16header-center-width, parameter, 16header-height, parameter, 16header-left, parameter, 16header-left-width, parameter, 16header-right, parameter, 16header-right-width, parameter, 16header-separator, parameter, 16hhc-basename, parameter, 39hhp-template, parameter, 39hhx-basename, parameter, 39highlight-source, parameter, 7hyphenate, parameter, 16
Iignore-navigation-links, parameter, 29. See alsochain-topics, parameter{{image(URI)}}, page header/footer variable,24imagemap, 20index-column-gap, parameter, 17index-range-separator, parameter, 8
i
Conversa User Guide
Jjavascripts, parameter, 29justified, parameter, 17
Llink-auto-text, parameter, 8link-bullet, parameter, 17
Mmark-external-links, parameter, 30mark-important-steps, parameter, 9MathJax, 29, 30mathjax, parameter, 29mathjax-url, parameter, 30MathML, 29, 30menucascade-separator, parameter, 17
Nnavigation-icon-height, parameter, 30navigation-icon-suffix, parameter, 30navigation-icon-width, parameter, 31note-icon-height, parameter, 17note-icon-list, parameter, 8note-icon-suffix, parameter, 17note-icon-width, parameter, 18number, parameter, 8number-separator1, parameter, 8number-separator2, parameter, 9number-toc-entries, parameter, 33
O.odt, filename extension, 11. See alsoOpenOffice, output formatoutputclass, attribute, 7
Ppage-bottom-margin, parameter, 18pagebreak, processing-instruction, 13{{page-count}}, page header/footer variable,24page-height, parameter, 18page-inner-margin, parameter, 18{{page-number}}, page header/footer variable,24page-orientation, parameter, 18page-outer-margin, parameter, 18page-ref-after, parameter, 19page-ref-before, parameter, 19
{{page-sequence}}, page header/footervariable, 24, 25page-top-margin, parameter, 19page-width, parameter, 19paper-type, parameter, 19part-number-format, parameter, 9pdf-outline, parameter, 20plugin-id, parameter, 39plugin-index-basename, 39plugin-name, parameter, 39plugin-provider, parameter, 39plugin-toc-basename, parameter, 40plugin-version, parameter, 40Preferences dialog, 4prepend-chapter-to-section-number,parameter, 9Publish DITA MAP dialog, 2
Rremedy-number-format, parameter, 9.rtf, filename extension, 11. See alsoRTF, outputformat
Sscreen-resolution, parameter, 31{{section1-title}}, page header/footer variable,23show-draft-comments, parameter, 9show-external-links, parameter, 20show-imagemap-links, parameter, 20show-link-page, parameter, 20show-xref-page, parameter, 20syntax highlighting, 7
Ttitle-after, parameter, 10title-color, parameter, 20title-font-family, parameter, 20title-page, parameter, 10title-prefix-separator1, parameter, 11{{topic-title}}, page header/footer variable, 24, 25troubleSolution-number-format, parameter, 9two-sided, parameter, 21
Uul-li-bullets, parameter, 21unordered-step-bullets, parameter, 21use-note-icon, parameter, 11
ii
Conversa User Guide
Wwatermark, parameter, 21watermark-image, parameter, 11whc-index-basename, parameter, 38wh-collapse-toc, parameter, 34wh---CSS_VAR_NAME, parameter, 33whc-toc-basename, parameter, 38wh-index-numbers, parameter, 34wh-inherit-font-and-colors, parameter, 34wh-jquery, parameter, 34wh-layout, parameter, 35wh-local-jquery, parameter, 35wh-responsive-ui, parameter, 35wh-ui-language, parameter, 35wh-user-css, parameter, 36wh-user-footer, parameter, 36wh-user-header, parameter, 37wh-user-resources, parameter, 38wh-use-stemming, parameter, 35.wml, filename extension, 11. See alsoWordprocessingML, output format
XXFC, XSL-FO processor, 11, 22xfc-render-as-table, parameter, 22xhtml-mime-type, parameter, 31xref-auto-text, parameter, 11xsl-resources-directory, parameter, 12
iii
Conversa User Guide