Dost.jar and fo.jar

Overview of Dost.jar and FO.jarAryeh Sanders, Suite Solutions

Who Are We?Our MissionTo increase our customers’ profitability by significantly improving the efficiency of their information development and delivery processes.Qualitative AdvantageContent Lifecycle Implementation (CLI) is Suite Solutions’ comprehensive approach – from concept to publication – to maximizing the value of your information assets.Our professionals are with you at every phase, determining, recommending and implementing the most cost-effective, flexible and long term solution for your business.

IntroductionWe will discuss what exactly are dost.jar and fo.jar and the role they play in the DITA-OTQuick answers:dost.jar holds the Java code for the DITA-OT as a wholefo.jar holds the Java code for the FO plugin (otherwise known as PDF output)In both cases, the JAR files are simply a place to store Java code. As such, they each have a collection of different functions.We will discuss why you usually will NOT want to customize them, and some exceptions

OverviewHow to Build a New dost.jarOverview of Functions of dost.jarChanging dost.jar to Detect New Image TypesOverview of Functions of fo.jarHow to Build a New fo.jar

Dost.jar Source CodeNot available in the default DITA-OT downloadAvailable via CVS (the source control system) from SourceForgeAvailable as a separate download from SourceForgeCurrent stable version available here:http://sourceforge.net/projects/dita-ot/files/DITA-OT%20Stable%20Release/DITA%20Open%20Toolkit%201.5.1/DITA-OT1.5.1_src.zip/downloadYou may have to hunt for it; the name isn’t consistent between versions

Building dost.jarUnzip the source code over an existing copy of the DITA-OTYou may prefer to download a clean copy of the DITA-OT for thisNot all of the tools needed are included in the source code package, but they are in the full DITA-OT downloadSome files will overwrite each other, but this will create a copy of the DITA-OT with the source codeRun startcmd.batThis sets up various environment variables so that, for instance, you can run AntBuild dost.jarant -f buildPackage.xml package-javaYou’ll get some warnings, but if you get a successful build, that’s it

Overview of Functions of dost.jar

Layout of dost.jar Source Code

Layout of dost.jar Source CodeAlthough we can broadly define three different functions in dost.jar, they’re not organized that way in the source code.Instead it’s organized by specific function – the code is invoked through one of the files in the invoker folder; logging is done by code in the log folder, and so on

Dost.jar Functions (1)Java InvokerImplemented in the invoker folder in CommandLineInvoker.javaNot related to the other files in that folder(ExtensibleAntInvoker doesn’t seem to be used?)Does rely on other Java code for logging and so onIf you use the Java command line, and needed to add a command line parameter to the DITA-OT, then this is where to do itIf you wanted to add a new parameter /myparam:value, so you could use it like so:java -jar libost.jar /i:inputfile /transtype:xhtml /myparam:specialJust add:paramMap.put("/myparam", “my.ant.parameter");in the section with the rest of the parameters

Downside to Modifying dost.jardost.jar is not designed to be modified or extended. You have no easy way to upgrade dost.jar and retain your changes.Unlike most other parts of the toolkit, which support pluginsThere’s an easier way to achieve the same goal as the previous example:set ANT_OPTS="%ANT_OPTS% -Dmy.ant.parameter=value"This is usually true for most other changes you would wantThe DITA-OT still has known bugs, so even if you are satisfied with the current functionality, you may want to preserve your ability to upgrade to get bug fixesDITA itself gets updated, and you may want to benefit from new DITA 1.2 or eventually DITA 1.3 features when they come along

Basic Flow of CommandLineInvokerFirst, validate the parametersModify certain parameters to have a full path instead of a relative pathWrite the parameters to a temporary properties fileCall integratorCall Ant via the command line, with a custom logger and the properties file as parameters

Dost.jar Functions (2)IntegratorJava implementation for supporting pluginsSearches demo and plugins subfolders for folders that contain a file called plugin.xmlIf it has one, then it’s a pluginEach plugin.xml file has a list of plugin points it modifiesExample: demoita11lugin.xml:<feature extension="dita.specialization.catalog.relative”value="catalog.xml" type="file"/>This will take the contents of demoita11atalog.xml and put it into the dita.specialization.catalog.relative extension point.Plugin points are defined in many different files, all including _template in their namesExample: dita.specialization.catalog.relative is defined in catalog-dita_template.xmlIntegrator will take catalog-dita_template.xml, and generate catalog-dita.xml, inserting the appropriate data from the dita11 plugin

More About IntegratorWe’re not going into much more detail now – in short, Integrator reads plugin.xml from each plugin, and rewrites each _template file to create the “real” version of the file.catalog-dita_template.xml -> catalog-dita.xmlbuild_template.xml -> build.xmlbuild_general_template.xml -> build_general.xmlbuild_dita2eclipsehelp_template.xml -> build_dita2eclipsehelp.xmlbuild_preprocess_template.xml -> build_preprocess.xmlresource/messages_template.xml -> resource/messages.xmlxsl/common/allstrings_template.xml -> xsl/common/allstrings.xmlxsl/dita2xhtml_template.xsl -> xsl/dita2xhtml.xslxsl/dita2rtf_template.xsl -> xsl/dita2rtf.xslxsl/dita2odt_template.xsl -> xsl/dita2odt.xslxsl/dita2dynamicdita_template.xsl -> xsl/dita2dynamicdita.xslxsl/dita2fo-shell_template.xsl -> xsl/dita2fo-shell.xslxsl/dita2docbook_template.xsl -> xsl/dita2docbook.xslxsl/preprocess/maplink_template.xsl -> xsl/preprocess/maplink.xslxsl/preprocess/mapref_template.xsl -> xsl/preprocess/mapref.xslxsl/preprocess/mappull_template.xsl -> xsl/preprocess/mappull.xslxsl/map2plugin_template.xsl -> xsl/map2plugin.xslxsl/preprocess/conref_template.xsl -> xsl/preprocess/conref.xslxsl/preprocess/topicpull_template.xsl -> xsl/preprocess/topicpull.xsl

More About IntegratorWe will point out, though, that there are a bunch of different ways that Integrator inserts data into the template:All defined in the platform folder, new ones added from time to timeInsertAction.javaInsertActionRelative.javaInsertAntActionRelative.javaInsertCatalogActionRelative.javaInsertDependsAction.java…Selected by the _template files themselves:E.g. catalog-dita_template.xml contains:<dita:extensionid="dita.specialization.catalog“ behavior="org.dita.dost.platform.InsertAction“xmlns:dita="http://dita-ot.sourceforge.net" /><dita:extension id="dita.specialization.catalog.relative“ behavior="org.dita.dost.platform.InsertCatalogActionRelative“xmlns:dita="http://dita-ot.sourceforge.net" />

Dost.jar Functions (3)Pipeline FunctionsYou can run the DITA-OT without the other functions. As long as you have created all those files that integrator will create, and as long as you invoke the toolkit directly via Ant, you can publish your DITA output just fine.And it should be slightly faster! (Maybe a second or two)These are also an assortment of unrelated functionsThey are tied together by the DITA-OT pipeline – the DITA-OT runs the DITA files through a series of steps. The steps are coordinated by Ant, but some of the steps are implemented in JavaThe are called by the <pipeline> task in AntExample:<pipeline message="Generate list." module="GenMapAndTopicList”basedir="${basedir}" inputmap="${args.input}”tempdir="${dita.temp.dir}“ extparam="ditadir=${dita.dir};validate=${validate};generatecopyouter=${generate.copy.outer};outercontrol=${outer.control};onlytopicinmap=${onlytopic.in.map};outputdir=${output.dir};transtype=${transtype}" />

Pipeline FunctionsCurrent modules in use:ChunkCoderefConrefPushDebugAndFilterEscapeUnicodeGenMapAndTopicListIndexTermExtractKeyrefMoveLinksMoveMetaTopicMergeEach one does something different

Most of the names are pretty clear

They are only chained together through Ant, so there’s no direct relationship between them

There’s some infrastructure within the Java code that passes the call from Ant to a specific module

invokerntInvoker calls pipelineipelineFacade which calls modulesoduleFactory which gets the actual module

The actual modules are defined in the modules folderSome Specific Pipeline Functionsgen-list, otherwise known as GenMapAndTopicListRuns through the whole ditamap and all the referenced files, and generates a list of files that will be needed by Ant for each future step. This is how Ant knows which files need to be copied.This is where conreflistand imagelist are generatedAlthough the files conref.list and image.list are generated laterDebugAndFilterAdds debug attributes to each file in a new copy in the temp directory and filters out elements that are supposed to be removed as per the instructions in the ditaval filextrc, xtrf attributesNot all modules are always usedTopicMerge is used by PDF, but not by XHTMLTopicMerge creates one big fileIt can take a stylesheet as a parameter, so the TopicMerge processing in PDF is actually partially Java (the merge) and partially a stylesheet (the actual form of the output from this step)

Adding a New Image Type to the DITA-OTThe current implementation of the DITA-OT decides what’s an image based on a hard coded listWhich module would have this code?It uses a utility function in utilileUtils.javaisSupportedImageFileSupported images also appear in the function isValidTargetBoth require a one line modification:|| lcasefn.endsWith(Constants.FILE_EXTENSION_GIF)The constants are defined in utilonstants.java:/**.gif extension.*/ public static final String FILE_EXTENSION_GIF = ".gif";Just add the appropriate lines, and rebuild, and you’ve added support for a new image type

FO.jarLike dost.jar, it’s a catch-all

fo.jar Folder StructureThe sourceis in src:

Dost.jar and fo.jar

More Related Content

Dost.jar and fo.jar