5. Specifying a conversion

Figure 2. Buttons allowing to add, edit and remove conversion specifications
Buttons allowing to add, edit and remove conversion specifications
Procedure 3. How to specify a conversion
  1. Click the Add button.

    You may also select a conversion close to the one you intend to add and then click the Edit button to modify it. In such case, do not forget to change the name of the edited conversion specification. By doing so, you'll add a new conversion rather than modify the existing one.

  2. Give a name to your conversion specification and specify whether it creates a file or a directory.

    1. Specify the name of your conversion in the Name text field. This name must be an XML Name, that is, to make it simple, it cannot start with a digit and it cannot contain space characters.

    2. Optionally describe what does your conversion in the Description text field.

    3. Optionally associate an icon to your conversion.

      This icon may be selected from a predefined list (button ) or found in an external file (button ).

    4. Optionally associate a category to your conversion. Generally, the type of the input document (DocBook, DITA, XHTML, etc) is used as a category.

    5. Optionally associate an icon to the category.

    6. Check the File radio button if your conversion creates a output file and in such case, specify the standard extension used for such file in the Extension text field.

      If your conversion requires/creates an output directory, check the Directory radio button. In this case, note that:

      • The output directory will be created if it does not exist. If it exists, the output directory will be made empty before performing the conversion (you'll have to confirm this interactively).

      • You'll need to specify the output directory to the XSLT stylesheet (see the transform step) and/or to the process command (see the process step) by referencing the %O variable in an XSLT style parameter value and/or in the process command.

  3. Optional step:

  4. Specify the transform step, if any.

    1. Check the XSLT stylesheet checkbox if your conversion requires the XML input file to be transformed using an XSLT stylesheet.

    2. Specify the URL of the XSLT stylesheet in the corresponding text field.

      The button next to the text field allows you to choose this XSLT stylesheet using the standard file chooser dialog box.

    3. Check the "Is XSLT Version 2.0 stylesheet" checkbox if the stylesheet you have chosen conforms to the XSLT Version 2 standard.

    4. Optionally, specify one or more XSLT stylesheet parameters by clicking the Add button.

      Note that an XSLT stylesheet parameter value may reference one or more of the following variables: %I, %X, %W, %T, %O, %S. (Appendix A, Variables describes all the variables supported by XMLmind XSL Utility.)

      [Tip]

      Select a parameter in the XSLT stylesheet parameters table by clicking on it and then, click the Documentation link to display its online documentation in your Web browser.

      Unfortunately, the Documentation link is often disabled (``grayed'') because many XSLT stylesheets are not documented and/or do not support any parameter.

  5. Specify the process step, if any.

    1. Check the Run XSL-FO processor radio button and select this XSL-FO processor using the corresponding combobox if your conversion requires processing an XSL-FO file generated by the transform step (or specified as the XML input file when the transform step is omitted).

      Alternatively, check the Execute process command radio button when your XSL-FO processor is not one of the three processors supported by XMLmind XSL Utility (example: Antenna House Formatter; see Appendix C, Using Antenna House Formatter as your XSL-FO processor) or when your conversion requires a specific post-transformation processing (see Appendix D, Using XMLmind XSL Utility to convert a DocBook 4 document to HTML Help (.chm file) for an example of such case).

      [Note]About the process command

      The process command is evaluated (after all the % variables have been substituted with their values) by cmd.exe on Windows and by /bin/sh on Linux/Mac.

      The process command may reference one or more of the following variables: %I, %X, %W, %T, %O, %S. (Appendix A, Variables describes all the variables supported by XMLmind XSL Utility.)

      Finally, there are many cases where the transform step is all what you need (examples: conversion to HTML, Eclipse Help). In such case, simply check the No processing radio button.

    2. When the Run XSL-FO processor radio button has been checked, optionally specify one or more XSL-FO processor parameters by clicking the Add button.

      These parameters are documented in Appendix B, XSL-FO processor parameters.

      Note that an XSL-FO processor parameter value may reference one or more of the following variables: %I, %X, %W, %T, %O, %S. (Appendix A, Variables describes all the variables supported by XMLmind XSL Utility.)

5.1. Specifying the conversion of a DITA topic or map

Figure 3. The DITA tab
The DITA tab
Procedure 4. Minimal specification
  1. Check the "Input file is a DITA topic or map" checkbox.

  2. If you want to generate an HTML-based format (XHTML, HTML Help, etc), specify a relative path in the "Copy images to" field. For example, specify "images".

  3. Select the format of the generated document from the "Target format" combobox.

5.1.1. Reference of the fields found in the DITA tab

Default language

Specifies the main language of the document. Examples: en, en-US, fr, fr-CA. This information is needed in order to sort the index entries. By default, this information is taken from the xml:lang attribute of the root element of the topic map (if any, "en" otherwise).

Conditional processing profile

Apply specified conditional processing profile (a .ditaval file) to the topics.

The buttons found at the top/right of this field allow respectively to:

  • clear this field;

  • edit, or simply view, the .ditaval file specified in this field;

  • specify the URL of a .ditaval file by selecting it using a file chooser dialog box.

Table of Contents

Specifies whether to automatically generate a Table of Contents and, if a Table of Contents is to be generated, where to generate it. Frontmatter means at the beginning of the document. Backmatter means at the end of the document.

This option, like List of Figures, List of Tables, List of Examples and Index, is mainly useful when working with maps or individual topics. When working with a bookmap, the preferred way to specify the location, if any, of a Table of Contents is to do it in the bookmap itself. In all cases, what's specified in the bookmap has priority over the value of this option.

List of Figures

Specifies whether to automatically generate a List of Figures and, if a List of Figures is to be generated, where to generate it.

List of Tables

Specifies whether to automatically generate a List of Tables and, if a List of Tables is to be generated, where to generate it.

List of Examples

Specifies whether to automatically generate a List of Examples and, if a List of Examples is to be generated, where to generate it.

Index

Specifies whether to automatically generate an Index and, if an Index is to be generated, where to generate it.

Copy images to

Copy the image files referenced in the topics to specified directory. If specified path is relative, it is relative to the output directory.

When this field is left empty, the generated document will reference the image files using absolute URLs. This is harmless for PDF, RTF, etc, files because at the end of the conversion process, such files will embed a copy of the image files. However, this is rarely what is wanted for HTML-based formats (XHTML, Java Help, HTML Help, etc).

Chunk mode

Allowed values are Automatic, Single and None.

Chunk Automatic means: ignore the chunk specification found in the topic map and output a single chunk for the print medium; honor the chunk specification for the screen medium.

Chunk None means ignore the chunk specification found in the topic map and output a single chunk. As explained above, chunk None is implicit for some formats (PostScript, PDF, RTF, etc),

Both the None and Single values may be used to force the generation of a single output file. Chunk Single allows to reuse a map designed to output multiple HTML pages in order to generate a single HTML file or a PDF file.

Target format

The format of the generated document. This format must match the XSLT stylesheet specified in the "XSLT stylesheet" field of the Transform tab:

FormatXSLT Stylesheet
XHTML 1.0xslutil_install_dir/addon/config/dita/xsl/xhtml/xhtml.xsl
XHTML 1.1xslutil_install_dir/addon/config/dita/xsl/xhtml/xhtml1_1.xsl
HTML 4.01xslutil_install_dir/addon/config/dita/xsl/xhtml/html.xsl
XHTML 5xslutil_install_dir/addon/config/dita/xsl/xhtml/xhtml5.xsl
Web Helpxslutil_install_dir/addon/config/dita/xsl/webhelp/webhelp.xsl
Web Help containing XHTML 5 pagesxslutil_install_dir/addon/config/dita/xsl/webhelp/webhelp5.xsl
HTML Help (.chm)xslutil_install_dir/addon/config/dita/xsl/htmlhelp/htmlhelp.xsl
Eclipse Helpxslutil_install_dir/addon/config/dita/xsl/eclipsehelp/eclipsehelp.xsl
EPUB 2xslutil_install_dir/addon/config/dita/xsl/epub/epub.xsl
EPUB 3xslutil_install_dir/addon/config/dita/xsl/epub/epub3.xsl
PostScriptxslutil_install_dir/addon/config/dita/xsl/fo/fo.xsl
PDFxslutil_install_dir/addon/config/dita/xsl/fo/fo.xsl
OpenOffice (.odt, OpenOffice.org 2+)xslutil_install_dir/addon/config/dita/xsl/fo/fo.xsl
RTF (MS-Word 2000+)xslutil_install_dir/addon/config/dita/xsl/fo/fo.xsl
WordprocessingML (MS-Word 2003+)xslutil_install_dir/addon/config/dita/xsl/fo/fo.xsl
Office Open XML (.docx, MS-Word 2007+)xslutil_install_dir/addon/config/dita/xsl/fo/fo.xsl
XSL-FOxslutil_install_dir/addon/config/dita/xsl/fo/fo.xsl

Of course, it is also possible to specify XSLT stylesheets which specialize the above ones.

Preprocessor messages

Specifies the level of verbosity of the DITA preprocessor. Allowed values are (from not verbose to very verbose): None, Information, Verbose, Debug.

5.2. Specifying the conversion of an XHTML page

If the document being converted is an XHTML 1.0, 1.1 or 5.0 file then you must check the "Input file is XHTML" checkbox. Note that if you forget to do this, the conversion will work, but the images referenced in the XHTML input file will all be omitted in the output file and also, all the CSS styles possibly specified in the XHTML input file will be ignored.

[Note]Converting plain HTML (that is, not XHTML) files

XMLmind XSL Utility does not support converting plain HTML (that is, not XHTML) files. However XMLmind XSL Server does. Therefore when XMLmind XSL Utility is used to configure the conversions of XMLmind XSL Server, possibly using the -p command-line option, then also check "Input file is XHTML" when the input file is plain HTML.

Figure 4. The XHTML tab
The XHTML tab

The CSS styles options allow to specify what to do with the CSS styles possibly found in the XHTML input file. (These CSS styles are found in style attributes, style elements and link elements pointing to CSS stylesheets.)

Ignore

Ignore all the CSS styles specified in the XHTML input file.

Apply

Apply to the intermediate XSL-FO file generated by the XHTML XSLT 2 stylesheets all the CSS styles specified in the XHTML input file.

This is the default option. It emulates —to a certain extent— how a Web browser typically renders an HTML page.

Use this CSS stylesheet

Ignore all the CSS styles specified in the XHTML input file. Instead apply to the intermediate XSL-FO file generated by the XHTML XSLT 2 stylesheets all the styles found in specified CSS stylesheet.

5.3. Specifying the conversion of DocBook v5.1+ assembly

If the document being converted is DocBook v5.1+ assembly (i.e. not a book, chapter, article, etc) then you must check the "Input file is a DocBook Assembly" checkbox.

Figure 5. The DocBook Assembly tab
The DocBook Assembly tab

An assembly may contain several structure elements. A structure element may specify several output formats (web, print, etc)[2]. When this is the case, you'll want to specify which structure you want to convert and also which output format you target.

Structure ID

The value of the xml:id attribute of the structure element to be converted. By default, it's the first structure found in the assembly.

Output format

One of the output formats specified in the structure selected using the above "Structure ID" field. By default, it's the value of the defaultformat attribute of the structure if any, the “implicit format” otherwise.

The “implicit format” matches output, filterin, filterout elements without any outputformat attribute.

Multiple output formats separated by ";" may be specified. For example, "web;print" means output format is "web" OR "print".

Preprocessor messages

Specifies the level of verbosity of the assembly processor. Allowed values are (from not verbose to very verbose): None, Information, Verbose, Debug.

5.4. Customizing a stock XSLT stylesheet

The "XSLT stylesheet" frame found at the top of the Transform tab has buttons allowing to easily customize the XSLT stylesheet currently selected.

5.4.1. Using an existing XSLT stylesheet customization

If you already have an XSLT stylesheet customization, simply specify its location by clicking , the "Choose XSLT stylesheet" button.

However if you do this, please make sure that your XSLT stylesheet customization imports the stock XSLT stylesheet by using an URL starting with "xslutil-config:". DITA example:

xsl:import href="xslutil-config:dita/xsl/fo/fo.xsl"/>

5.4.2. Creating an XSLT stylesheet customization

If you want to create an XSLT stylesheet customization, please proceed as follows:

  1. Click Customize.

    You are prompted for the .xsl save file which is to contain your customization.

    Clicking OK creates a custom XSLT stylesheet based on the currently selected stock XSLT stylesheet.

    A custom XSLT stylesheet created this way merely imports the original XSLT stylesheet. Example:

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    version="1.0">
      <xsl:import href="xslutil-config:docbook/xsl/fo/docbook.xsl"/>
      <!-- REDEFINE PARAMETERS AND ATTRIBUTE-SETS HERE -->
    </xsl:stylesheet>

    Note that it's not possible to create a customization of a custom XSLT stylesheet.

  2. Click Edit.

    If the custom XSLT stylesheet has been created using the Customize button, this button starts the "XMLmind XSL Customizer" application in order to edit it. Otherwise, this button starts a helper application allowing to edit XSLT files.

    [Tip]

    Clicking Edit while keep the Shift key pressed allows to start a helper application rather than the "XMLmind XSL Customizer" application.

If you have customized an XSLT stylesheet and want to revert to the original XSLT stylesheet, simply click Revert.

5.4.3. The "XMLmind XSL Customizer" application

5.4.3.1. Introduction

The "XMLmind XSL Customizer" application is a companion application embedded in XMLmind XML Editor and XMLmind XSL Utility.

Figure 6. "XMLmind XSL Customizer" main window
"XMLmind XSL Customizer" main window

This application is invoked by clicking the Edit XSLT stylesheet button found in XMLmind XML Editor and XMLmind XSL Utility. It allows to modify a custom XSLT stylesheet created by clicking the Customize XSLT stylesheet button found in XMLmind XML Editor and XMLmind XSL Utility.

A custom XSLT stylesheet created this way merely imports the stock XSLT stylesheet. Example:

<?xml version="1.0" encoding="UTF-8"?>
<?stylesheet-label ACME Corp. Styles?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="dita-config:xsl/fo/fo.xsl"/>
  <!-- REDEFINE PARAMETERS AND ATTRIBUTE-SETS HERE -->
</xsl:stylesheet>

"XMLmind XSL Customizer" is not an XSLT editor. However it allows to:

  • add or change attributes in some of the attribute sets supported by the XSLT stylesheet,

  • change the value of some of the parameters supported by the XSLT stylesheet,

and this, without prior knowledge of XSLT.

5.4.3.2. Reference
Toolbar buttons
New

Create a customization of an existing XSLT stylesheet. This button displays the standard file chooser dialog box allowing to choose the XSLT stylesheet for which a customization is to be created.

Open

Open a custom XSLT stylesheet previously created by clicking the New button. This button displays the standard file chooser dialog box allowing to choose the custom XSLT stylesheet to be opened.

Close

Close currently opened XSLT stylesheet.

Save

Save the changes made to currently opened XSLT stylesheet.

Save As

Save currently opened XSLT stylesheet to a different file.

Help

Display this online help.

Quit

Close "XMLmind XSL Customizer" main window.

[Tip]

Because "XMLmind XSL Customizer" is an (embedded) application and not a modal dialog box, you can keep it open while converting an XML document in XMLmind XML Editor or in XMLmind XSL Utility. This allows to experiment with attribute sets and parameters until you are satisfied with the result of the conversion.

Information fields about the currently opened XSLT stylesheet
Description:

Short description of the currently opened custom XSLT stylesheet. XMLmind XML Editor requires a custom XSLT stylesheet to have such description.

Customization of:

Read-only text field: URI of the stock XSLT stylesheet for which the currently opened XSLT stylesheet is a customization.

Attribute Sets tab buttons
Add

Add an attribute to one of the attribute sets supported by currently opened XSLT stylesheet.

This button displays the Add/Edit attribute dialog box. How to use this dialog box is described in the example below.

Figure 7. The Add/Edit attribute dialog box
The Add/Edit attribute dialog box
[Note]

XMLmind XSL Customizer is designed for users who cannot “program in XSLT”. These users are expected to enter literal values, not XSLT elements, in the Custom value field. For example, they are expected to enter something like:

20pt

as the value of the font-size attribute, and not something like:

<xsl:value-of select="$body.font.master * 2"/>
<xsl:text>pt</xsl:text>

However, if the user happens to know what she/he is doing and nevertheless enters one or more XML nodes in the Custom value field, then XMLmind XSL Customizer will ask her/him to confirm that this is really what she/he wants and make it work.

Edit

Modify currently selected attribute.

This button displays the Add/Edit attribute dialog box.

Remove

Remove currently selected attribute.

Documentation

Start the web browser and make it display the page containing the documentation about currently selected attribute. This button is disabled (grayed) when such documentation is not available. For now, only the DocBook XSL Stylesheets provide some documentation for their attribute sets.

Parameters tab buttons
Add

Set one of the parameters supported by currently opened XSLT stylesheet.

This button displays the Add/Edit parameter dialog box. How to use this dialog box is described in the example below.

Figure 8. The Add/Edit parameter dialog box
The Add/Edit parameter dialog box
[Note]

XMLmind XSL Customizer is designed for users who cannot “program in XSLT”. These users are expected to enter literal values, not XSLT elements, in the Custom value field. For example, they are expected to enter something like:

40pt

as the value of the body.start.indent parameter, and not something like:

<xsl:value-of select="$body.font.master * 4"/>
<xsl:text>pt</xsl:text>

However, if the user happens to know what she/he is doing and nevertheless enters one or more XML nodes in the Custom value field, then XMLmind XSL Customizer will ask her/him to confirm that this is really what she/he wants and make it work.

Edit

Modify currently selected parameter.

This button displays the Add/Edit parameter dialog box.

Remove

Remove currently selected parameter.

Documentation

Start the web browser and make it display the page containing the documentation about currently selected parameter. This button is disabled (grayed) when such documentation is not available.

Example 1. When converting a DITA map to PDF, give a light gray background to all the topic titles

This is specified by adding attribute background-color=#CCCCCC to the attribute-set called topic-title.

  1. Select the Attribute Sets tab.

  2. Click Add. This displays the Add/Edit attribute dialog box.

  3. In the "Attribute set name:" combobox, select topic-title.

  4. In the "Attribute:" combobox, type "background-color" or select this commonly used attribute from the drop down list.

    The "Original value:" read-only text field remains empty, indicating that the stock XSLT stylesheet does not specify attribute topic-title/background-color.

  5. In the "Custom value:" field, type "#CCCCCC".

    Or more simply, click "Edit style attribute" and use the background-color editor to specify a light gray color.

  6. Click OK to close the dialog box.

Example 2. When converting a DITA map to PDF, use a 12pt base font size

This is specified by setting parameter base-font-size to 12pt.

  1. Select the Parameters tab.

  2. Click Add. This displays the Add/Edit parameter dialog box.

  3. In the "Parameter name:" combobox, select base-font-size.

    The "Original value:" read-only text field changes to "10pt", which is the value of parameter base-font-size specified in the stock XSLT stylesheet.

  4. In the "Custom value:" field, type "12pt".

  5. Click OK to close the dialog box.



[2] The outputformat attribute set on output, filterin, filterout elements allows to specify “classes” of output formats rather than actual output formats (PDF, DOCX, EPUB, etc).