2.2. Convert a DocBook document to RTF
Prev | 2. Commented examples | Next

### 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" "%_"' />
        </sequence>
      </macro>
    </command>

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

          <!-- 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">
            <imagedata fileref="resources/{$url.rootName}.png" />
          </cfg:extract>

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

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

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

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

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

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.

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

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.

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.

| References to really absolute resources are not modified in the copy of the document.
| References to PNG, GIF, JPEG graphics files are modified to point to the copies which are made in directory `resources/`.
| 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.
| Converts all images found in directory `raw/` to PNG images created in directory `resources/`.
| Copies resources internally used by the `xsl/fo/docbook.xsl` XSLT style sheet to where the FO processor can find them.
| Transforms the copy of the document `__doc.xml` to XSL-FO file `__doc.fo`.

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>

| Convert XSL-FO file `__doc.fo` to local RTF file `__doc.rtf`.
| 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.

Prev | Up | Next
2.1. Convert explicitly or implicitly selected ``para`` to a ``simpara`` | Home | 2.3. Convert ImageDemo document to HTML