Documentation Framework
A documentation framework is an XML schema for semantically structured authoring, that supports single-sourcing of content. The content then becomes the raw material that can be extracted (via XSLT) based on conditional logic, into a variety of presentation formats (e.g., PDF, XHTML, Webhelp), with custom rendering with the application of style sheets (CSS).
I chose to go with the DITA documentation framework because it supports such a wide variety of transformation scenarios.
DITA
DITA stands for the Darwin Information Type Architecture.
DOST
I don’t know where the name DOST came from, but it’s the DITA-OT Eclipse Plugin. It’s also called the DITA-OT runtime, and its required for invoking Ant from Java code. It’s packaged as an executable jar file:
dost.jar
If you start the Java environment with the -jar switch, and the name of the jar file (and no other parameters), you can view a list of the parameters that you can supply to dost.jar.
E.g.,
C:\Users\Chris>java.exe -jar "C:\Program Files\eclipse\plugins\com.oxygenxml.editor_15.0.0.v2013071613\frameworks\dita\DITA-OT\lib\dost.jar"
java -jar lib/dost.jar [mandatory parameters] [options]
| Mandatory Parameter | Description |
|---|---|
| /i: | Specifies path and name of the input file. |
| /transtype: | Specifies the transformation type. |
| Options | Description |
| -help, -h | print this message |
| -version | print the version information and exit |
| /basedir: | specify the working directory |
| /ditadir: | specify the toolkit’s home directory. Default is “temp” |
| /outdir: | specify the output directory |
| /tempdir: | pecify the temporary directory |
| /logdir: | specify the log directory |
| /ditaext: | specify the file extension name to be used in the temp directory. Default is ”.xml” |
| /filter: | specify the name of the file that contains the filter/flaggin/revision information |
| /draft: | specify whether to output draft info. Valid values are “no” and “yes”. Default is “no” (hide them). |
| /artlbl: | specify whether to output artwork filenames. Valid values are “no” and “yes” |
| /ftr: | specify the file to be placed in the BODY running-footing area |
| /hdr: | specify the file to be placed in the BODY running-heading area |
| /hdf: | specify the file to be placed in the HEAD area |
| /csspath: | specify the path for css reference |
| /css: | specify user css file |
| /cssroot: | specify the root directory for user specified css file |
| /copycss: | specify whether to copy user specified css files. Valid values are “no” and “yes” |
| /indexshow: | specify whether each index entry should display within the body of the text itself. Valid values are “no” and “yes” |
| /outext: | specify the output file extension for generated xhtml files. Default is ”.html” |
| /xsl: | specify the xsl file used to replace the default xsl file |
| /xslpdf: | specify the xsl file used to replace the default xsl file when transforming pdf |
| /cleantemp: | specify whether to clean the temp directory before each build. Valid values are “no”and “yes”. Default is “yes” |
| /foimgext: | specify the extension of image file in legacy pdf transformation. Default is ”.jpg” |
| /fooutputrellinks | For legacy PDF transform: determine if links are included in the PDF. Values are “no” and “yes”. Default is “no”. |
| /foincluderellinks | For default PDF transform: determine which links are included in the PDF. Values are”none”, “all”, and “nofamily”. Default is “none”. |
| /odtincluderellinks | For default ODT transform: determine which links are included in the ODT. Values are”none”, “all”, and “nofamily”. Default is “none”. |
| /retaintopicfo | specify that topic.fo file should be preserved in the output directory. Specify any value, such as “yes”, to preserve the file. |
| /javahelptoc: | specify the root file name of the output javahelp toc file in javahelp transformation. Default is the name of the input ditamap file |
| /javahelpmap: | specify the root file name of the output javahelp map file in javahelp transformation. Default is the name of the input ditamap file |
| /eclipsehelptoc: | specify the root file name of the output eclipsehelp toc file in eclipsehelp transformation. Default is the name of the input ditamap file |
| /eclipsecontenttoc: | specify the root file name of the output Eclipse content provider toc file in eclipsecontent transformation. Default is the name of the input ditamap file |
| /xhtmltoc: | specify the root file name of the output xhtml toc file in xhtml transformation |
| /xhtmlclass: | specify whether DITA element names and ancestry are included in XHTML class attributes. Only “yes” and “no” are valid values. The default is yes. |
| /usetasklabels: | specify whether DITA Task sections should get headings. Only “YES” and “NO” are valid values. The default is NO. |
| /validate: | specify whether the ditamap/dita/xml files to be validated |
| /outercontrol: | specify how to respond to the overflowing dita/topic files. Only “fail”, “warn” and “quiet” are valid values. The default is warn. |
| /generateouter: | specify how to deal with the overflowing dita/topic files. Only “1”, “2” and “3” arevalid values. The default is 1.k /onlytopicinmap: specify whether make dita processor only resolve dita/topic files which are referenced by primary ditamap files Only “true” and “false” are valid values. The default is false. |
| /debug: | specify whether extra debug information should be included in the log. Only “yes” and “no” are valid values. The default is no. |
| /grammarcache: | specify whether grammar pool caching is used when parsing dita files. Only “yes” and”no” are valid values. The default is yes. |
| /odtimgembed: | specify whether embedding images as binary data in odt transform. Only “yes” and “no”are valid values. The default is yes. |
Apache Ant
Apache Ant is a Java builder program, similar to GNU Make. It processes Ant Projects, which are packaged as buildfiles.
Buildfile
A Buildfile is an XML file that contains an Ant Project. You use an Ant Project to coordinate the building of code and doc projects. This approach provides the flexibility needed for automated processing of custom configurations.
Projects contain groups of processing instructions called Targets. The processing instructions that a Target contains corresponds to a unique processing scenario.
A Target contains a group of Task Elements (Tasks) that are executed in sequence.
Each Task Element can have a unique ID attribute, which you can then use to reference that Task from any other Task.
oXygen’s DITA Buildfile
This is part of the oXygen XML Eclipse plugin installation:
C:\Program Files\eclipse\plugins\com.oxygenxml.editor_15.0.0.v2013071613\frameworks\dita\DITA-OT\build.xml
When you use oXygen to build a documentation set in Eclipse, this is the build file that oXygen feeds to Ant.
This build file imports several other build files into it; one for each transformation type (e.g., PDF, WebHelp, etc.).
It imports the build file that you use for the 3rdPartySDK docs:
C:\Program Files\eclipse\plugins\com.oxygenxml.editor_15.0.0.v2013071613\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\build_dita.xml
oXygen Custom Editor Variables
${ProductName1}=3rdPartySDK
${FeatureName1}=Push Verification
${FeatureName2}=Soft Token
${CompanyName}=3rdParty
DITA Scenario
Advanced
Additional Arguments
Example
-diagnostics -logger org.apache.tools.ant.XmlLogger -logfile buildlog.xml
