Your SlideShare is downloading. ×
Dost.jar and fo.jar
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Dost.jar and fo.jar

650

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
650
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. Overview of Dost.jar and FO.jar
    Aryeh Sanders, Suite Solutions
  • 2. Who Are We?
    Our Mission
    To increase our customers’ profitability by significantly improving the efficiency of their information development and delivery processes.
    Qualitative Advantage
    Content 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.
  • 3. Clients and Partners
    3
    Private and Confidential
    Suite Solutions©2009
  • 4. Introduction
    We will discuss what exactly are dost.jar and fo.jar and the role they play in the DITA-OT
    Quick answers:
    dost.jar holds the Java code for the DITA-OT as a whole
    fo.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
  • 5. Overview
    How to Build a New dost.jar
    Overview of Functions of dost.jar
    Changing dost.jar to Detect New Image Types
    Overview of Functions of fo.jar
    How to Build a New fo.jar
  • 6. Dost.jar Source Code
    Not available in the default DITA-OT download
    Available via CVS (the source control system) from SourceForge
    Available as a separate download from SourceForge
    Current 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/download
    You may have to hunt for it; the name isn’t consistent between versions
  • 7. Building dost.jar
    Unzip the source code over an existing copy of the DITA-OT
    You may prefer to download a clean copy of the DITA-OT for this
    Not all of the tools needed are included in the source code package, but they are in the full DITA-OT download
    Some files will overwrite each other, but this will create a copy of the DITA-OT with the source code
    Run startcmd.bat
    This sets up various environment variables so that, for instance, you can run Ant
    Build dost.jar
    ant -f buildPackage.xml package-java
    You’ll get some warnings, but if you get a successful build, that’s it
  • 8. Overview of Functions of dost.jar
  • 9. Layout of dost.jar Source Code
  • 10. Layout of dost.jar Source Code
    Although 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
  • 11. Dost.jar Functions (1)
    Java Invoker
    Implemented in the invoker folder in CommandLineInvoker.java
    Not 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 on
    If you use the Java command line, and needed to add a command line parameter to the DITA-OT, then this is where to do it
    If you wanted to add a new parameter /myparam:value, so you could use it like so:java -jar libdost.jar /i:inputfile /transtype:xhtml /myparam:special
    Just add:paramMap.put("/myparam", “my.ant.parameter");in the section with the rest of the parameters
  • 12. Downside to Modifying dost.jar
    dost.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 plugins
    There’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 want
    The 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 fixes
    DITA itself gets updated, and you may want to benefit from new DITA 1.2 or eventually DITA 1.3 features when they come along
  • 13. Basic Flow of CommandLineInvoker
    First, validate the parameters
    Modify certain parameters to have a full path instead of a relative path
    Write the parameters to a temporary properties file
    Call integrator
    Call Ant via the command line, with a custom logger and the properties file as parameters
  • 14. Dost.jar Functions (2)
    Integrator
    Java implementation for supporting plugins
    Searches demo and plugins subfolders for folders that contain a file called plugin.xml
    If it has one, then it’s a plugin
    Each plugin.xml file has a list of plugin points it modifies
    Example: demodita11plugin.xml:<feature extension="dita.specialization.catalog.relative”value="catalog.xml" type="file"/>This will take the contents of demodita11catalog.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 names
    Example: dita.specialization.catalog.relative is defined in catalog-dita_template.xml
    Integrator will take catalog-dita_template.xml, and generate catalog-dita.xml, inserting the appropriate data from the dita11 plugin
  • 15. More About Integrator
    We’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.xml
    build_template.xml -> build.xml
    build_general_template.xml -> build_general.xml
    build_dita2eclipsehelp_template.xml -> build_dita2eclipsehelp.xml
    build_preprocess_template.xml -> build_preprocess.xml
    resource/messages_template.xml -> resource/messages.xml
    xsl/common/allstrings_template.xml -> xsl/common/allstrings.xml
    xsl/dita2xhtml_template.xsl -> xsl/dita2xhtml.xsl
    xsl/dita2rtf_template.xsl -> xsl/dita2rtf.xsl
    xsl/dita2odt_template.xsl -> xsl/dita2odt.xsl
    xsl/dita2dynamicdita_template.xsl -> xsl/dita2dynamicdita.xsl
    xsl/dita2fo-shell_template.xsl -> xsl/dita2fo-shell.xsl
    xsl/dita2docbook_template.xsl -> xsl/dita2docbook.xsl
    xsl/preprocess/maplink_template.xsl -> xsl/preprocess/maplink.xsl
    xsl/preprocess/mapref_template.xsl -> xsl/preprocess/mapref.xsl
    xsl/preprocess/mappull_template.xsl -> xsl/preprocess/mappull.xsl
    xsl/map2plugin_template.xsl -> xsl/map2plugin.xsl
    xsl/preprocess/conref_template.xsl -> xsl/preprocess/conref.xsl
    xsl/preprocess/topicpull_template.xsl -> xsl/preprocess/topicpull.xsl
  • 16. More About Integrator
    We 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 time
    InsertAction.java
    InsertActionRelative.java
    InsertAntActionRelative.java
    InsertCatalogActionRelative.java
    InsertDependsAction.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" />
  • 17. Dost.jar Functions (3)
    Pipeline Functions
    You 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 functions
    They 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 Java
    The are called by the <pipeline> task in Ant
    Example:<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}" />
  • 18. Pipeline Functions
    Current modules in use:
    Chunk
    Coderef
    ConrefPush
    DebugAndFilter
    EscapeUnicode
    GenMapAndTopicList
    IndexTermExtract
    Keyref
    MoveLinks
    MoveMeta
    TopicMerge
    • Each one does something different
    • 19. Most of the names are pretty clear
    • 20. They are only chained together through Ant, so there’s no direct relationship between them
    • 21. There’s some infrastructure within the Java code that passes the call from Ant to a specific module
    • 22. invokerAntInvoker calls pipelinePipelineFacade which calls modulesModuleFactory which gets the actual module
    • 23. The actual modules are defined in the modules folder
  • Some Specific Pipeline Functions
    gen-list, otherwise known as GenMapAndTopicList
    Runs 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 generated
    Although the files conref.list and image.list are generated later
    DebugAndFilter
    • Adds 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 file
    xtrc, xtrf attributes
    Not all modules are always used
    TopicMerge is used by PDF, but not by XHTML
    TopicMerge creates one big file
    It 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)
  • 24. Adding a New Image Type to the DITA-OT
    The current implementation of the DITA-OT decides what’s an image based on a hard coded list
    Which module would have this code?
    It uses a utility function in utilFileUtils.java
    isSupportedImageFile
    Supported images also appear in the function isValidTarget
    Both require a one line modification:
    || lcasefn.endsWith(Constants.FILE_EXTENSION_GIF)
    The constants are defined in utilConstants.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
  • 25. FO.jar
    Like dost.jar, it’s a catch-all
  • 26. fo.jar Folder Structure
    The sourceis in src:
  • 27. fo.jar Components (1)
    In comidiomincwsopentopicxslextension:
    DitaVersion.java reports back to Ant what version of DITA is being processed
    Ant uses it to decide which version of the stylesheets to use; the regular version for older versions of DITA, and the versions with _1.0 in the name for newer versions
    In comsuitesolditaot
    DetectLang.javareports the first xml:lang attribute in your files, which is used if you didn’t set the document.locale parameter to let the system know what language settings to use
  • 28. fo.jar Components (2)
    In comidiomincwsopentopicfo:
    In xep: there are Java classes that call RenderX XEP. This is used if you use XEP for your FO processor.
    In i18n: there is code that is used together with your i18n configuration file and your font-mappings file to set fonts on a character-by-character basis. The Java code simply searches for each character listed in the i18n configuration files and marks it. The actual font is selected with the i18n-postprocess.xsl stylesheet.
    In index2: this code is the code that constructs the index. The actual display is left to the stylesheets, but it searches for all the indexterms, constructs, groups, and sorts the list, and inserts it into one of the intermediate files, namely stage1.xml. That file is the input to the main stylesheets.
  • 29. More About fo.jar Index Sorting
    Several known bugs
    We’re working on them – if you have new ones, please report them on SourceForge
    fo.jar does grouping and sorting
    Grouping is deciding which words go in the “A” section, which in the “B” section, which in the “Special Characters” section, and so on
    Sorting is putting them in the right order within that section
    The index configuration files are used for grouping, not sorting
    Sorting is handed off to the icu4j.jar library when it’s present. Otherwise, it uses built-in Java sorting, which is fine for English, but not for many languages
  • 30. Questions?
    Any questions?
    Be in touch!Aryeh Sandersaryehs@suite-sol.com

×