Output generation with 2.x or 3.x

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

Note: All codeblocks are examples only. Any ¶ symbols are not part of the code sample. They show required line breaks so you can view the single line in its entirety within publishing constraints.

The 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. Since it defines the properties, you must include them in the build.bat file.

Table 1. dita-startcmd-ot-build defined properties required for inclusion

Property

Function

 
<property name="outgen.job.ot.dita.command" 
	location="${outgen.ot.dir}/bin/dita"/>

Defines path to DITA file that runs the build

 
<property name="outgen.job.ot.command.propertyfile" 
	location="${outgen.job.dir}/build.properties"/>

Defines location and name of build.properties

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

Defines the input ditamap

 
<property name="outgen.job.ot.command.format" 
	value="${outgen.job.ot.properties.transtype}"/>

Defines the transtype
Table 2. Additional properties defined

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>

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"/>

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>

Determines OS type 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 and then passes in the JAVA_HOME environment variable to identify the location of the Java installation that should be used

  • (Windows) Runs cmd.exe with the appropriate arguments
  • (Linux) Makes both the dita file and the batch.sh file executable and then runs the batch.sh file
Note: Any resulting warnings or errors are redirected to the build log. This process doesn't use the standard -l logging parameter.

(Windows) The build.bat file

A typical build.bat file 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.


"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

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

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

The rest of the file provides the required parameters and specifies the input ditamap, transtype, and properties file in the build.bat file's command line.

  • -i: specifies the full path to the input ditamap
  • -f: specifies 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 the resulting log as verbose
    Note: 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 in build.bat command line is 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.

#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 need to create build properties files outside of CCMS Output Generator, remember to escape backslashes (\\) in file paths. Within CCMS Output Generator this is not an issue, since CCMS Output Generator dynamically creates this file.