2.2. Convert a DocBook document to RTF

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

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

    <mkdir dir="images/callouts" />9
    <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">10
      <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" />11
    </transform>

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

    <upload base="%2">13
      <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

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

6

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

7

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.

8

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

9

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

10

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

11

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>

12

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

13

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.