Install and configure a rendition engine

Two types of rendition engines are supported for IBM FileNet P8 Publishing, the Rendition Engine that uses the Liquent Rendering Engine for rendering and the DITA Rendition Engine that uses the DITA Open Toolkit for rendering.

Rendition Engine Installation

To install and configure the Rendition Engine, follow the instructions in IBM FileNet Rendition Engine installation and upgrade.

DITA Rendition Engine Installation

To install the DITA Rendition Engine

  1. Download the DITA Open Toolkit from http://sourceforge.net/projects/dita-ot/.
  2. Expand the package (in .zip or .tar.gz format) to the desired installation directory on either the Content Engine server or a server that is mapped or mounted on the Content Engine server.

    For best performance this location should be a local path on the Content Engine server. Specifying a UNC path allows one DITA Open Toolkit location to support multiple DITA rendition engines.The advantage of a shared location is that there is only one location to update with new versions of the DITA Open Toolkit. The disadvantage is that loading the DITA Open Toolkit over the network is slower.

  3. This step is required for versions of the DITA OT that are 1.4.3 or higher. For versions of DITA OT before, 1.4.3, skip this step:
    Copy the jars files from DITA_HOME\lib\saxon to DITA_HOME\lib. This adds the jars files to the CLASSPATH when FileNet P8 invokes the DITA OT.

Considerations for installations of DITA Open Toolkit on UNIX systems

Some UNIX installations of the DITA OT have incorrect permission settings for the ant tools. If you get the following error:

2008-09-15T18:46:04.652Z 00D300D3 PUBL FNRCE0000I - INFO DITA OT ERROR>java.io.IOException: ant^@: not found

Verify that file permissions in the DITA-OT/tools/ant/bin directory are set to grant execute privilege.

Configuration Steps to Support Japanese Content

In order to support Japanese content, you must configure DITA OT to use fonts that generate Japanese characters. You must select the desired font and integrate it with the DITA OT.

NOTE  The following configuration steps are based on DITA OT 1.4.3 using the new FOP plug-in for PDF.

The following example shows the procedure to add the MS Gothic True Type font. However, you can replace MS Gothic True Type with the font that best suits your needs.

  1. Modify DITA_HOME\demo\fo\build.xml to support Japanese characters:

    Change from:

    <property name="document.locale" value="en_US" />

    To this:

    <property name="document.locale" value="ja_JP" />

  2. Generate a font metrics XML file from the True Type font you will use. Below is an example using msgothic.ttc to generate a font metrics file msgothic.xml under the fonts directory:

    cd DITA_HOME\demo\fo\fop
    mkdir fonts
    java -cp build\fop.jar;lib\avalon-framework-4.2.0.jar;lib\commons-logging-1.0.4.jar;lib\commons-io-1.3.1.jar;lib\xmlgraphics-commons-1.3.1.jar org.apache.fop.fonts.apps.TTFReader -ttcname "MS Gothic" C:\WINDOWS\Fonts\msgothic.ttc fonts\msgothic.xml

    Because msgothic.ttc is a True Type Collection, use the -ttcname option to specify which font in the collection you are using.

  3. Modify the font metrics file generated by the previous step, replace existing values for font-name, full-name and family-name with MSGothic.

    NOTE  Do not change the value of the ttc-name element.

  4. Modify DITA_HOME\fo\fop\conf\fop.xconf and add the XML below (replace hard coded paths as needed). The XML below must be placed within the <fonts></fonts> tags.

    <fonts>
    :
    <font metrics-url="file:///C:/sccs/DITA-OT1.4.3/demo/fo/fop/fonts/msgothic.xml" embed-url="file:///C:/WINDOWS/Fonts/msgothic.ttc" kerning="yes">
    <font-triplet name="MSGothic" style="normal" weight="normal"/>
    <font-triplet name="MSGothic" style="normal" weight="bold"/>
    <font-triplet name="MSGothic" style="italic" weight="normal"/>
    <font-triplet name="MSGothic" style="italic" weight="bold"/>
    </font>

  5. Customize the fonts and internationalization of FO output under the Customization directory. First, copy the system font-mappings.xml to customization directory.

    cd DITA_HOME\demo\fo\Customization
    copy ..\cfg\fo\font-mappings.xml .\fo\

    Open fo\font-mappings.xml and modify all references to char-set Japanese such that the font-face value is MSGothic

    <physical-font char-set="Japanese">
    <font-face>MSGothic</font-face>
    </physical-font>

  6. Next modify fo\i18n\ja_JP.xml to include the character range of your selected font.

    cd DITA_HOME\demo\fo\Customization
    copy ..\cfg\fo\i18n\ja_JP.xml .\fo\i18n\

    Open fo\i18N\ja_JP.xml to expand the character range for non-kanji characters.

    <alphabet char-set="Japanese">
    <character-set>
    :
    <character-range>
    <start include="yes">&#x2160;</start>
    <end include="yes">&#x21AF;</end>
    </character-range>
    <character-range>
    <start include="yes">&#x2460;</start>
    <end include="yes">&#x24EF;</end>
    </character-range>
    <character-range>
    <start include="yes">&#xFF00;</start>
    <end include="yes">&#xFFEF;</end>
    </character-range>

    <!-- DOUBLE VERTICAL LINE / PARALLEL TO -->
    <character>&#x2225;</character>

    </character-set>
    </alphabet>

  7. Enable the customization code above:

    cd DITA_HOME\demo\fo\Customization
    copy catalog.xml.orig catalog.xml

    Open catalog.xml and un-comment the following two lines for font mappings and Japanese internationalization.
    <uri name="cfg:fo/font-mappings.xml" uri="fo/font-mappings.xml"/>
    <uri name="cfg:fo/i18n/ja_JP.xml" uri="fo/i18n/ja_JP.xml"/>

The DITA OT is now configured to support the MSGothic Japanese character font.

Considerations for multi-process access to DITA Open Toolkit installations

If you have multiple processes accessing a single DITA Open Toolkit (OT) installation, you might encounter intermittent input and output failures as the DITA Open Toolkit reads the build files. To avoid this problem, each server instance that will perform DITA publishing must have a separate DITA OT installation. If multiple server instances are operating on the same machine, there must be multiple instances of the DITA OT installed, one for each server instance. DITA publishing for each server instance must be configured with the Queue Item Max Dispatchers set to 1, instead of the default value of 2. This results in one publishing thread operating on a separate DITA OT installation.

In this example a cluster has 3 server instances, all operating a single server, and all server instances are to be configured to support DITA publishing.

  1. Install three instances of DITA OT, for example:
    1. C:\DITAOT-S1
    2. C:\DITAOT-S2
    3. C:\DITAOT-S3
  2. Start FileNet Enterprise Manager and configure DITA publishing.
    1. Navigate to the Sites node.
    2. Expand to display server instances under Virtual Servers.
    3. For each server instance:
      1. Right click on a server instance and select Properties.
      2. Click on Publishing tab.
      3. Select the Override inherited setting check box.
      4. Modify Queue Item Max Dispatchers from 2 to 1.
      5. Verify that the DITA Open Toolkit location in the DITA Rendition Engine Connection is unique for this server instance.

Each server instance will have a unique DITA OT location and will have one publishing thread available to use that DITA OT installation.

NOTE  This procedure requires that you do not configure Liquent publishing at the server instance level unless you want Liquent and DITA publishing to share a single publishing thread. Specify Liquent publishing configuration at a higher level then the server instance, for example, the Site level. Here you can specify as many publishing threads as needed for Liquent publishing.