XMLmind logo

XMLmind DITA Converter Manual

  

Chapter 2. Getting started Previous topic Parent topic Child topic Next topic

1. Using the ditac command-line utility Previous topic Parent topic Child topic Next topic

In this chapter, we'll explain how to run the ditac command-line utility by using examples. You'll find all the DITA input files used to run the following examples in the ditac_install_dir/docsrc/manual/ directory.
Tip
Tip
XMLmind DITA Converter has been integrated to XMLmind XSL Utility Opens in new window, which is part of the XMLmind XSL-FO Converter Opens in new window commercial product.
Unlike ditac, which is a command-line utility, XMLmind XSL Utility is a graphical tool. It makes it easy parameterizing the DITA conversion process and then performing document conversions.
Figure 2-1. XMLmind XSL Utility main window
xslutil_dita_menu.png
Moreover, this graphical tool comes in a Windows, auto-installable, self-contained, setup.exe distribution(1) which includes Apache FOP Opens in new window, XMLmind XSL-FO Converter Opens in new window and ditac.
If you just want to quickly and easily evaluate all the potential of ditac, you may want to download XMLmind XSL Utility Evaluation Edition from XMLmind XSL-FO Converter web site Opens in new window. Do not be surprised because XMLmind XSL Utility Evaluation Edition generates output containing random duplicate letters. Of course, this does not happen with Professional Edition!

§ Converting a document to PDF

Converting a document, for example this manual, to PDF is done by executing the following command:
$ ditac -r manual_files out/manual.pdf manual.ditamap
The output directory out/ is automatically created if it does not already exist.
The -r manual_files option is needed here only because this manual references audio and video files and also contains TeX/LaTeX math. However, specifying this option (or -resources or -i or -images, which are all aliases of -r) is generally not needed when converting a DITA document to any of the XSL-FO based output formats (PDF, DOCX, ODT, etc).
Unless you have specified in the ditac.options file which XSL-FO processor to use, you'll have to execute:
$ ditac -fop /opt/fop/fop -r manual_files \
  out/manual.pdf manual.ditamap
or:
$ ditac -xep /opt/xep/xep -r manual_files \
  out/manual.pdf manual.ditamap
or:
$ ditac -ahf "C:\AHFv6\AHFCmd.exe" -r manual_files \
  out/manual.pdf manual.ditamap
Tip
Tip
No need to declare Apache FOP using the -fop command-line option if you have installed the distribution called ditac-N_N_N-plus-fop.zip. This distribution contains most recent Apache FOP Opens in new window (including hyphenation and MathML support). This XSL-FO processor is automatically registered with ditac and thus, ready to be used to generate PDF or PostScript.
The XSL-FO processors allowing to generate PDF also allows to generate PostScript®. Example:
$ ditac -r manual_files out/manual.ps manual.ditamap
Notice how the output format is determined by examining the filename extension of the output file.

Table 2-1. Supported filename extensions

Format Extensions
XHTML 1.0 .html, .htm, .xhtml
EPUB 2 .epub
HTML Help .chm
PDF .pdf
PostScript® .ps
RTF (can be opened in Word 2000+) .rtf, .doc
WordprocessingML( can be opened in Word 2003+) .wml, .xml
Office Open XML (can be opened in Word 2007+) .docx
OpenOffice (can be opened in OpenOffice/LibreOffice 2+) .odt
Note that ditac also allows to convert one or more topic files rather than a single map or bookmap file:
$ ditac -toc \
    out/draft.pdf embed1.dita embed2.dita
Ditac does not generate a table of contents (TOC) by default. Unless the input file is a bookmap containing an empty toc element in its frontmatter/booklists descendant element, you'll have to explicitly use the -toc option. Using the -toc option when the input file already specifies a TOC is harmless, so you could as well add a -toc line to your ditac.options file.

§ Converting a document to a word processor format

Converting a document to a word processor format just requires the use of an XSL-FO processor different from the one which generates PDF or PostScript. Fortunately all this automatically handled by ditac.
Convert a document to RTF (can be opened in Word 2000+):
$ ditac -r manual_files out/manual.rtf manual.ditamap
Unless you have specified in the ditac.options file which XSL-FO processor to use, you'll have to execute:
$ ditac -xfc /opt/xfc/fo2rtf -r manual_files \
  out/manual.rtf manual.ditamap
Suffice to specify the location of fo2rtf (fo2rtf.bat on Windows). Using this location, ditac infers the locations of fo2wml, fo2docx and fo2odt.
WARNING
WARNING
XMLmind XSL-FO Converter Opens in new window Evaluation Edition (download page Opens in new window) generates output containing random duplicate letters. This makes this edition useless for any purpose other than evaluating XMLmind XSL-FO Converter. Of course, this does not happen with XMLmind XSL-FO Converter Professional Edition!
Convert a document to WordprocessingML (can be opened in Word 2003+):
$ ditac -xfc /opt/xfc/fo2wml -r manual_files out/manual.word.xml manual.ditamap
Convert a document to Office Open XML (can be opened in Word 2007+):
$ ditac -xfc /opt/xfc/fo2docx -r manual_files out/manual.docx manual.ditamap
Convert a document to OpenOffice (can be opened in OpenOffice.org 2+):
$ ditac -xfc /opt/xfc/fo2odt -v -p number all -r manual_files \
    out/manual.odt manual.ditamap
Useful options
  • -v instructs ditac to print progress messages on the console. Recommended when converting large documents.
  • "-p number all" passes parameter "number" with value "all" to the XSLT stylesheets which generate the XSL-FO. The XSL-FO are then converted to OpenOffice format by the means of XMLmind XSL-FO Converter. The number='all' parameter instructs the XSLT stylesheets to number topics, tables and figures.

§ Converting a document to XHTML

Converting a document to multi-page XHTML 1.0 is done by executing the following command:
$ ditac -r manual_files -p xsl-resources-directory res \
    out/manual/_.html manual.ditamap
  • All the files generated by ditac are created in the out/manual/ directory.
  • "-r manual_files" instructs ditac to copy all the image, audio, video files referenced by the input DITA document to out/manual/manual_files/, possibly converting some image files from a non-supported format (e.g. TIFF) to a format supported by web browsers (e.g. PNG).
    Remember
    Remember
    Specifying the -r option (or -resources or -i or -images, which are all aliases of -r) when generating an output format based on XHTML/HTML is needed in almost all the use cases.
  • "-p xsl-resources-directory res" instructs ditac to copy all the resources needed by the XSLT stylesheets (CSS stylesheet, navigation icons, etc) to out/manual/res/.
    Remember
    Remember
    Specifying a value for the xsl-resources-directory parameter when generating an output format based on XHTML/HTML is needed in almost all the use cases.
  • Notice the strange name of the output file: out/manual/_.html. In fact, this name is just used to specify the filename extension of the output files. The actual basenames of the output files are determined by examining the chunk and copy-to attributes possibly specified in the DITA map.
    Note that a command-line like:
    $ ditac -r manual_files -p xsl-resources-directory res \
    out/manual/foo.html manual.ditamap
    works fine too. The only difference is that in such case, when a basename is needed and cannot be determined by examining the chunk and copy-to attributes specified in the DITA map, ditac will use "foo" as a basename and you may end up having some output files called foo.html, foo-2.html, foo-3.html, etc. When the basename is specified as "_", it is the basename of the DITA map which is used. That is, you may have some output files called manual.html, manual-2.html, manual-3.html, etc.
What if you want to convert a document to HTML 4.01 or XHTML 1.1 or XHTML 5 rather than to XHTML 1.0? We have learned that there is no way to specify this using a filename extension. The answer is: use the -format option (or -f in its short form). Example:
$ ditac -format html \
    -r manual_files -p xsl-resources-directory res \
    out/manual/_.html manual.ditamap

Table 2-2. Supported output formats

Format Name
XHTML 1.0 xhtml
XHTML 1.1 xhtml1.1
HTML 4.01 html
XHTML 5 xhtml5. html5 is an alias for xhtml5.
Web Help containing XHTML 1 pages webhelp
Web Help containing XHTML 5 pages webhelp5
HTML Help htmlhelp
Eclipse Help eclipsehelp
EPUB 2 epub
EPUB 3 epub3
PDF pdf
PostScript® ps
RTF (can be opened in Word 2000+) rtf
WordprocessingML( can be opened in Word 2003+) wml
Office Open XML (can be opened in Word 2007+) docx
OpenOffice (can be opened in OpenOffice.org 2+) odt
XSL-FO fo
Useful options
  • "-p chain-pages both". This XSLT stylesheet parameter specifies that a header and a footer containing navigation icons should be generated in order to link together all the HTML pages.
  • "-p chain-topics yes". This XSLT stylesheet parameter specifies that navigation icons should be generated in order to link together all the topics.
  • "-p default-table-width 100%". Unless this XSLT stylesheet parameter is specified (or the expanse="page" attribute is specified for all tables), web browsers tend to layout the generated HTML tables in order to make them as narrow as possible.
A full-fledged command-line is thus:
$ ditac -r manual_files -p xsl-resources-directory res \
    -p number all \
    -p chain-pages both \
    -p chain-topics yes \
    -p default-table-width 100% \
    out/manual/_.html manual.ditamap
What if you want to generate a single XHTML page rather than multiple XHTML page? No need to create a new DITA map for that. Simply specify option "-chunk single" (or -c in its short form).
$ ditac -chunk single \
    -r manual_files -p xsl-resources-directory res \
    out/manual.html manual.ditamap

§ Converting a document to Web Help

Converting a document to Web Help is similar to converting a document to multi-page XHTML 1. The main difference is that you need to explicitly specify -format webhelp:
$ ditac -format webhelp \
    -r manual_files -p xsl-resources-directory res \
    webhelp/_.html manual.ditamap
If you prefer to generate Web Help containing XHTML 5 pages rather than XHTML 1 pages, then specify -format webhelp5.
Remember
Remember
Do not specify any of the following command-line options when generating Web Help: -toc, -index.

§ Converting a document to HTML Help

Converting a document to HTML Help is done by executing the following command:
C:\> ditac -r manual_files -p xsl-resources-directory res \
    out\manual.chm manual.ditamap
Unless you have specified in the ditac.options file the location of hhc.exe, you'll have to execute:
C:\> ditac -hhc "C:\Program Files\HTML Help Workshop\hhc.exe" \
    -r manual_files -p xsl-resources-directory res \
    out\manual.chm manual.ditamap
Remember
Remember
Do not specify any of the following command-line options when generating HTML Help: -toc, -index.

§ Converting a document to Eclipse Help

Converting a document to Eclipse Opens in new window Help is similar to converting a document to multi-page XHTML. The main difference is that you need to explicitly specify -format eclipsehelp:
$ ditac -format eclipsehelp \
    -r manual_files -p xsl-resources-directory res \
    out/com.acme.widget.userguide/_.html manual.ditamap
In order to deploy the generated Eclipse Help, you need to copy the output directory as a whole (com.acme.widget.userguide/ in the case of the above example) to the plugins/ directory of Eclipse and then use a text or XML editor to modify the generated output_directory/plugin.xml:
<plugin name="EDIT HERE: title of this help" 
        id="EDIT HERE: unique.id.of.this.plugin"
        provider-name="EDIT HERE: author, company or organization"
        version="1.0.0">
   <extension point="org.eclipse.help.toc">
      <toc file="toc.xml" primary="true"/>
   </extension>
   <extension point="org.eclipse.help.index">
      <index file="index.xml"/>
   </extension>
</plugin>
If you do not want to hand edit plugin.xml, suffice to pass extra XSLT stylesheet parameters to ditac:
$ ditac -format eclipsehelp \
    -p plugin-name "ACME Widget User's Guide" \
    -p plugin-id com.acme.widget.userguide \
    -p plugin-provider "ACME Corp." \
    -r manual_files -p xsl-resources-directory res \
    out/com.acme.widget.documentation/_.html manual.ditamap
Remember
Remember
If you want to see your document by selecting Help → Help Contents in Eclipse:
  1. Do not specify any of the following command-line options when generating Eclipse Help: -toc, -index.
  2. Parameter plugin-id is required to have the same value as the basename of the the output directory (com.acme.widget.userguide/ in the case of the above example).
  3. Copy this output directory to eclipse_install_dir/dropins/ and not eclipse_install_dir/plugins/.

§ Converting a document to EPUB

Converting a document to EPUB Opens in new window Help is done by executing the following command:
$ ditac -r manual_files -p xsl-resources-directory res \
    out/manual.epub manual.ditamap
If you prefer to generate EPUB 3 rather than EPUB 2, then specify -format epub3.
Remember
Remember
Do not specify any of the following command-line options when generating EPUB: -toc. Note that you may specify option -index.
 (1) Of course, a .zip distribution is also available for platforms other than Windows.