2.2. Convert a DocBook document to RTF

This example is taken from XXE_install_dir/addon/config/docbook/xslMenu.incl.

<command name="docb.convertToRTF">
  <macro>
    <sequence>
      <command name="selectFile" parameter="saveFileURL" />
      <command name="docb.toRTF" parameter='"%0" "%1" "%_"' />1
    </sequence>
  </macro>
</command>

<command name="docb.toRTF">
  <process>
    <mkdir dir="resources" />2
    <mkdir dir="raw" />3
    <copyDocument to="__doc.xml">4

      <!-- Do *not* declare the svg namespace.  We want svg:svg to be
           a Name, not a QName. -->
      <cfg:extract xmlns="" xpath="//imageobject/svg:svg" toDir="raw">5
        <imagedata fileref="resources/{$url.rootName}.png" />
      </cfg:extract>

      <resources match="(https|http|ftp)://.*" />6
      <resources match=".+\.(png|jpg|jpeg|gif)"
                 copyTo="resources" />7
      <resources match="(?:.+/)?(.+)\.(\w+)"
                 copyTo="raw" referenceAs="resources/$1.png" />8
      <resources match=".+" 
                 copyTo="resources" />
    </copyDocument>

    <convertImage from="raw" to="resources" format="png" />9

    <mkdir dir="images/callouts" />10
    <copyProcessResources resources="xsl/images/draft.png" to="images" />
    <copyProcessResources resources="@xsl/images/callouts/png_callouts.list" 
                          to="images/callouts" />

    <transform stylesheet="xsl/fo/docbook.xsl" 
               file="__doc.xml" to="__doc.fo">11
      <parameter name="use.extensions">1</parameter>
      <!-- Cannot work and generates a lot of error messages. -->
      <parameter name="graphicsize.extension">0</parameter>

      <parameter name="paper.type">A4</parameter>

      <parameter name="generate.toc">%0</parameter>
      <parameter name="toc.section.depth">3</parameter>
      <parameter name="section.autolabel">%1</parameter>

      <parameter name="callout.graphics">1</parameter>

      <parameter name="shade.verbatim">1</parameter>

      <parameter name="ulink.show">0</parameter>

      <parameterGroup name="docb.toRTF.transformParameters" />12
    </transform>

    <processFO processor="XFC" file="__doc.fo" to="__doc.rtf">13
      <parameter name="outputEncoding">Cp1252</parameter>
      <parameterGroup name="docb.toRTF.XFCParameters" />
    </processFO>

    <upload base="%2">14
      <copyFile file="__doc.rtf" to="%2" />
    </upload>
  </process>
</command>
1

The docb.toRTF process command is passed 3 arguments:

%0

For which elements a Table Of Contents (TOC) is to be created. Example: "/book toc /article toc".

%1

1 if a TOC is to be generated, 0 otherwise.

%2

The URL of the RTF file to be created.

2

Images referenced in the DocBook document which are in formats supported by the XFC FO processor (GIF, JPEG and PNG) will be copied to directory resources/.

3

Images referenced in the DocBook document which are in formats not supported by the XFC FO processor will be copied to directory raw/ in order to be converted.

4

Copy document being edited as __doc.xml in the temporary process directory.

The copied document is flattened: all references to external entities and all XIncludes are expanded.

As specified by extract and resources, references to resources such as external graphics files (example: <imagedata fileref="XXX"/>) are modified in the copied document to point to copies which are local to the temporary process directory.

5

Embedded SVG graphics (svg:svg allowed in "-//OASIS//DTD DocBook SVG Module V1.0//EN") are extracted to directory raw/.

The svg:svg element is replaced by a properly initialized imagedata element which is easily handled by the XSLT style sheet and then by the FO processor (it is translated by the XSLT style sheet to a fo:external-graphic).

Caution

DocBook documents are conforming to a DTD and therefore they are not namespace aware in XXE. That's why the svg prefix must not be declared.

By doing this, svg:svg is understood by XXE as being {}svg:svg. If you declare the svg prefix, svg:svg is understood as being {http://www.w3.org/2000/svg}svg, which is wrong in the case of DocBook+SVG.

6

References to really absolute resources are not modified in the copy of the document.

7

References to PNG, GIF, JPEG graphics files are modified to point to the copies which are made in directory resources/.

8

References to other graphics files are modified to point to the converted images that will be generated in directory resources/. The graphics files in formats other that PNG, GIF, JPEG are copied as is in directory raw/, waiting to be converted.

9

Converts all images found in directory raw/ to PNG images created in directory resources/.

10

Copies resources internally used by the xsl/fo/docbook.xsl XSLT style sheet to where the FO processor can find them.

11

Transforms the copy of the document __doc.xml to XSL-FO file __doc.fo.

12

This parameterGroup allows XXE users to easily customize the XSLT style sheet by adding or replacing parameters.

Example of such parameterGroup added to XXE_user_preferences_dir/addon/customize.xxe:

  <parameterGroup name="docb.toRTF.transformParameters">
    <parameter name="callout.graphics">0</parameter>
    <parameter name="variablelist.as.blocks">1</parameter>
  </parameterGroup>
13

Convert XSL-FO file __doc.fo to local RTF file __doc.rtf.

14

Copies local RTF file __doc.rtf to its user-specified destination.

The element is called upload because, in Professional Edition, it can be used to publish the converted document by sending it (and all its associated resources, if needed to) to a remote FTP or WebDAV server.