Keep the topic.fo file for PDF outputs

The topic.fo file is very helpful for troubleshooting problems with styling in PDF outputs. These steps explain how to keep the topic.fo file during the build process.

When you generate a PDF using IXIASOFT CCMS Output Generator, the DITA Open Toolkit first combines all the topics in the map into one large XML file. It then converts that file into a different XML standard, called XSL-FO, and creates a new file named topic.fo. Finally, the DITA Open Toolkit sends the topic.fo file to your PDF renderer, which creates the PDF.

If your PDF is not styled the way you expect, you can look at the topic.fo file to see exactly what styling is being sent to the PDF renderer. Normally the topic.fo file is deleted during the build process, but you can keep it for troubleshooting. This procedure also returns the images.

Note: If you use Miramo for creating PDF outputs, it does not use XSL-FO nor create a topic.fo file. This option is not available.
  1. Open the %OutputGenDir%/data/outgen-init-client.xml file.
  2. Add the following property in the global properties section:
    <property name="outgen.job.keep.topicfo" value="yes"/>

    For example:

    <!--
    *********************************************************************************
    * Define global properties to use across all conductor files
    .
    * All properties defined outside of any targets will be executed when the
    * ant files are loaded and cannot contain properties defined by the running
    * job (ie.e:${outgen.job.*}) into its value except for ${outgen.job.ot.log.dir}
    *********************************************************************************
    -->
    <property name="outgen.job.keep.topicfo" value="yes"/>
  3. Save and close the file.
  4. Open the conductor file that contains the target to modify.
  5. In the target that you are using to generate the PDF, add the following line before calling the DITA-OT:
    <antcall target="ot_build_keep_topicfo"/>

    For example:

       ...
    
       <antcall target="ot_build_create"/>
       <antcall target="ot_build_add_ditaval_ifpresent"/>
       <antcall target="ot_build_clean_ot_temp"/>
       <antcall target="ot_build_keep_topicfo"/>
    
       <update-ot-build-file buildfile="${outgen.job.build.filename}">
          <param name="transtype" value="xhtml"/>
       </update-ot-build-file>
  6. Save and close the conductor file.

When you generate PDF output, the topic.fo file will be included in your output zip file.