Keep the topic.fo file

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

When you generate a PDF using the Output Generator, the DITA Open Toolkit first combines all the topics in the map into one large XML file. Next, it converts that file into a different XML standard, called XSL-FO, and creates a new file named topic.fo. Finally, the 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, it's very helpful to 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 retain it to help you troubleshoot. This procedure also returns the images.

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