Generating output when using 2.x or 3.x

CCMS Output Generator 7.2 dynamically creates a build.bat file, which calls a build.properties file to get all the other properties needed for the job.

The new dita-startcmd-ot-build macro

The dita-startcmd-ot-build macro is what essentially starts the build process. The macro is defined in the commontargets-system.xml file.

dita-startcmd-ot-build defines the following properties that must be included in the build.bat file:

Property	Defines
`<property name="outgen.job.ot.dita.command" location="${outgen.ot.dir}/bin/dita"/>`	The path to the DITA file that executes the build
`<property name="outgen.job.ot.command.propertyfile" location="${outgen.job.dir}/build.properties"/>`	The location and name of the build.properties file
`<condition property="outgen.job.ot.command.input" value="${outgen.job.ot.properties.args.input}" else="${outgen.job.source.filename}"> <isset property="outgen.job.ot.properties.args.input"/> </condition>`	The input ditamap
`<property name="outgen.job.ot.command.format" value="${outgen.job.ot.properties.transtype}"/>`	The transtype

The macro also defines additional properties:

Property Function

Property	Function
`<echoproperties destfile="${outgen.job.ot.command.propertyfile}"> <propertyset> <propertyref prefix="outgen.job.ot.properties."/> <mapper type="glob" from="outgen.job.ot.properties." to=""/> </propertyset> </echoproperties>`	This section creates the build.properties file by gathering all previously-defined properties prefixed with "outgen.job.ot.properties" and adding them to the file.
`<property name="outgen.job.ot.batchfile.content" value=""${outgen.job.ot.dita.command}" -i "${outgen.job.ot.command.input}" -f ${outgen.job.ot.command.format} -o "${outgen.job.ot.command.output.dir}" -propertyfile "${outgen.job.ot.command.propertyfile}" -v"/>`	This section creates the build.bat file.
`<switch value="${outgen.os.family}"> <case value="windows"> <dita_startcmd_ot_build_windows/> </case> <case value="unix"> <dita_startcmd_ot_build_linux/> </case> <default> <fail message="No DITA command for the OS family ${outgen.os.family}"/> </default> </switch>`	This section determines the OS and launches a macro appropriate for either Windows (dita_startcmd_ot_build_windows) or Linux (dita_startcmd_ot_build_linux), and it creates either a build.bat or a build.sh file with the appropriate command line. For both, the macro passes in the JAVA_HOME environment variable to identify the location of the Java installation that should be used. For Windows, the macro executes cmd.exe with the appropriate arguments. For Linux, the macro makes both the dita file and the batch.sh file executable and then executes the batch.sh file. In both the Windows and Linux macros, the warnings and errors are redirected into the build log. (This process doesn't use the standard -l logging parameter.)

<echoproperties destfile="${outgen.job.ot.command.propertyfile}">
	<propertyset>
		<propertyref prefix="outgen.job.ot.properties."/>
		<mapper type="glob" from="outgen.job.ot.properties.*" to="*"/>
	</propertyset>
	</echoproperties>

This section creates the build.properties file by gathering all previously-defined properties prefixed with "outgen.job.ot.properties" and adding them to the file.

<property name="outgen.job.ot.batchfile.content" 
	value="&quot;${outgen.job.ot.dita.command}&quot; 
	-i &quot;${outgen.job.ot.command.input}&quot; 
	-f ${outgen.job.ot.command.format} 
	-o &quot;${outgen.job.ot.command.output.dir}&quot; 
	-propertyfile &quot;${outgen.job.ot.command.propertyfile}&quot; 
	-v"/>

This section creates the build.bat file.

<switch value="${outgen.os.family}">
   <case value="windows">
      <dita_startcmd_ot_build_windows/>
   </case>
   <case value="unix">
      <dita_startcmd_ot_build_linux/>
   </case>
   <default>
      <fail message="No DITA command for the OS family ${outgen.os.family}"/>
   </default>
</switch>

This section determines the OS and launches a macro appropriate for either Windows (dita_startcmd_ot_build_windows) or Linux (dita_startcmd_ot_build_linux), and it creates either a build.bat or a build.sh file with the appropriate command line. For both, the macro passes in the JAVA_HOME environment variable to identify the location of the Java installation that should be used.

For Windows, the macro executes cmd.exe with the appropriate arguments.

For Linux, the macro makes both the dita file and the batch.sh file executable and then executes the batch.sh file.

In both the Windows and Linux macros, the warnings and errors are redirected into the build log. (This process doesn't use the standard -l logging parameter.)

The build.bat file for Windows

A typical build.bat file looks like this:


"C:Ixiasoft\outgen\og6.1\data\dita-ot-3.4\bin\dita" -i="C:\Ixiasoft\¶
outgen\og6.1\temp\Dita2df.whitel.32.1582745087104\content\authoring\¶
ojr1576871077845.ditamap" -f="pdf" -propertyfile="C:\Ixiasoft\out¶
gen\og6.1\temp\Dita2df.whitel.32.1582745087104\build.properties" -v

Note: The ¶ symbols are not part of the code sample. They show required line breaks so the single line can be displayed properly.

It is a single command line that calls the DITA-OT and passes three required properties to it. This command line is the same for Windows and Linux.

The first part of the file calls the DITA file within the DITA-OT\bin folder. This executes the DITA-OT:

"C:Ixiasoft\outgen\og6.1\data\dita-ot-3.4\bin\dita"

The remaining part provides the required parameters. The input ditamap, transtype, and properties file must be specified in the build.bat file's command line.

-i: specifies the full path to the input ditamap
-f: specifies the transtype (which must be a valid transtype defined within the DITA-OT)
-propertyfile: specifies the full path to the build.properties file, which contains any additional properties for the build.
-v: specifies that the resulting log should be verbose, which means that it should contain all information about the job. This is not a required parameter, but it ensures that the log you receive from the build contains all the information you need for troubleshooting.

The build.properties file

The build.properties file that is called by the command line in build.bat is also dynamically created when you generate output. This file includes all other properties needed for the job, including any properties you specify in the conductor target or on the Generate Output screen.

A typical build.properties file looks like this:

#Ant properties
#Wed Feb 26 14:24:55 EST 2020
args.draft=no
args.output=C:\:\\Ixiasoft\\outgen\\og6.1\\temp\\Dita2Pdf.whitel.32.1582745087107\\out
args.rellinks=none
clean.temp=yes
dita.dir=C:\:\\Ixiasoft\\outgen\\og6.1\\data\\dita-ot-3.4
dita.temp.dir=C:\:\\Ixiasoft\\outgen\\og6.1\\temp\\Dita2Pdf.whitel.32.1582745087107\\temp
pdf.formatter=fop
retain.topic.fo=no

The first two lines are comments that simply note the file’s purpose and date. The remaining lines specify values for parameters such as args.draft and args.output. It also specifies the DITA-OT to use and the temp directory for the build.

Note: If you ever need to create build properties files outside of CCMS Output Generator, keep in mind that backslashes in file paths must be escaped (\\). However, within CCMS Output Generator this is not an issue since CCMS Output Generator creates this file dynamically.