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 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.