Keep the topic.fo file for PDF outputs (DITA OT 2.x, 3.x)

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.

Versions 1.x of the DITA-OT included a build parameter, retain.topic.fo, that would keep the topic.fo file when set to yes. This parameter was deprecated beginning with DITA-OT 2.0, but you can enulate its functionality using an ANT copy task.

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.

Run the IXIASOFT CCMS Output Generator in debug mode.

This procedure works only if CCMS Output Generator is running in debug mode.

Add the following lines to your PDF target in the conductor-client.xml file:

<!-- Copy the topic.fo file to the output -->
<copy todir="${outgen.job.output.dir}">
    <fileset dir="${outgen.job.ot.temp.dir}" includes="topic.fo"/>
</copy>

In context:

<target name="BigCorp_PDF" depends="default_dependencies, flatten, resolve_container_keyref, extract_HiRes_images">
	<echostart>BigCorp_PDF</echostart>

	...

	<!-- This macro launches the OT "dita" command with all the parameters specified -->
	<dita_startcmd_ot_build/>

	<!-- Copy the topic.fo file to the output -->
	<copy todir="${outgen.job.output.dir}">
        <fileset dir="${outgen.job.ot.temp.dir}" includes="topic.fo"/>
    </copy>


	<!-- The macro cleans the OT folder based on the parameters specified in outgen-init-debug.xml -->
	<clean_ot_output/>

	...

	<echoend>BigCorp_PDF</echoend>
</target>

You do not need to restart the Ixiasoft Output Generator service.