Overview of the DITA Open Toolkit


Published on

Published in: Technology
1 Comment
1 Like
  • For the ANT file, I believe the entry needs to read 'property' instead of 'param'. I’d provide the full string, but SlideShare won’t accept my xml entries.
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Overview of the DITA Open Toolkit

  1. 1. Overview of the DITA Open Toolkit(Beginner Level) Adena FrazerSuite Solutions<br />
  2. 2. Who am I?<br />Background in Computer Science and Education<br />Experience in several computer companies over the past decade+<br />Web applications<br />Telecommunications<br />Early member of the Suite Solutions team<br />Various webinars and on-site training seminars in Boston and Santa Clara<br />PDF and HTML style sheet projects<br />FO plug-in support for PDF output<br />Project Management<br />
  3. 3. Overview of the DITA-OT:Main Topics<br /><ul><li>Overview of the DITA-OT
  4. 4. DITA-OT Architecture
  5. 5. Rendering Outputs using Different Transtypes
  6. 6. Customizing Processing using ANT
  7. 7. Filtering Output Using DITAVAL
  8. 8. DITA-OT Resources</li></li></ul><li>Overview of the DITA-OT <br />Checks that files are valid DITA<br />Performs Conditional Publishing<br />Includes or excludes topics and elements based on conditional attributes<br />product, audience, platform, otherprops<br />Checks and resolves references and links<br />topicrefs, conrefs, xrefs, related links <br />Dynamically generates links<br />Parent/child links generated based on map hierarchy and sequence<br />Related links generated based on relationship tables, grouped by type<br />
  9. 9. Overview of the DITA-OT <br />Merges all files together when necessary (PDF)<br />Dynamically creates TOC, index, bookmarks, and glossary, complete with internal referencing<br />Transforms preprocessed DITA into the desired output format using the relevant style sheets<br />Renders or compiles the final output: <br />FO to PDF<br />HTML Help, Eclipse Help, JavaHelp, etc.<br />The latest version is 1.5.1 which was released on June 18, 2010<br />
  10. 10. Overview of the DITA-OT:Main Topics<br /><ul><li>Overview of the DITA-OT
  11. 11. DITA-OT Architecture
  12. 12. Rendering Outputs using Different Transtypes
  13. 13. Customizing Processing using ANT
  14. 14. Filtering Output Using DITAVAL
  15. 15. DITA-OT Resources</li></li></ul><li>XML Parser<br /><ul><li>XERCES</li></ul>DITA-OT Architecture<br />DOST.jar<br />XSLTransforms<br />XML Parsing and Validation<br />Apache ANT<br />XSLstyle sheets<br />XSLT Engines<br /><ul><li>SAXON
  16. 16. XALAN
  17. 17. Pre-process
  18. 18. General processing
  19. 19. Transform to output format (xhtml, fo)
  20. 20. Batik.jar (FOP)
  21. 21. Resolver.jar (resolves DTD)
  22. 22. Icu4j.jar (internationalization)
  23. 23. Fop.jar</li></li></ul><li>Apache ANT (Another Neat Tool)<br />Build management tool similar to Batch or Make files from DOS – manages targets and dependencies<br />Used primarily by the Java community<br />Used as the control program for the DITA-OT workflow<br />Rebuilds all files – doesn’t do real dependency management.<br />ANT is used for common development tasks such as running the Toolkit, creating plug-ins, and HTML customization.<br />
  24. 24. DOST.jar<br />DOST – DITA Open Source Toolkit<br />Contains all of the JAVA code unique to the Toolkit as a whole<br />JAVA is a more general purpose programming language than ANT or XSLT<br />Some code is written in JAVA to improve performance.<br />Code is compiled<br />Source needs to be downloaded separately<br />When the source is changed, the jar needs to be recompiled.<br />
  25. 25. Other Java Components<br />There are many other Java libraries that may be in use by the toolkit such as:<br />Resolver.jar – resolves file references using catalog files such as catalog-dita.xml <br />Icu4j.jar – used for internationalization <br />Fop.jar – library for Formatting Objects Processor (included with the DITA-OT)<br />Batik.jar - graphics library used by FOP<br />
  26. 26. XSLT Engines - Saxon<br />Saxon is an XSLT processor created by Michael Kay. <br />Has both open source and commercial versions.<br />The original series of XSLT 1.0 processors has ended with version 6.5.5. It is not undergoing further development. <br />The new version, Saxon 9, implements the XSLT 2.0 specifications. It can process XSLT 1.0 files as well. This version is used by the DITA-OT.<br />
  27. 27. XSLT Engines - Xalan<br />Xalan is an XSLT and XPath Processor from the Apache Software Foundation.<br />It has some bugs and does not support XSLT2.<br />It used to be packaged with the DITA-OT due to licensing issues with Saxon.<br />These have been resolved and from version 1.4.3 and on, Saxon ships with the DITA-OT and not Xalan.<br />Saxon is the recommended XSLT processor to be used with the DITA-OT.<br />
  28. 28. Overview of the DITA-OT:Main Topics<br /><ul><li>Overview of the DITA-OT
  29. 29. DITA-OT Architecture
  30. 30. Rendering Outputs using Different Transtypes
  31. 31. Customizing Processing using ANT
  32. 32. Filtering Output Using DITAVAL
  33. 33. DITA-OT Resources</li></li></ul><li>Rendering Output:Build Scripts in the DITA-OT<br />Usebuild_demo.xml in the root of the ditaot directory to quickly test installation<br />Open the cmd window by double clicking on startcmd.bat<br />Type in ant –f build_demo.xml<br />Follow the instructions<br />Use sample ANT build scripts in the ditaot/samples/ant_sample/ directory.<br />Open the cmd window using startcmd.bat<br />Type in (for example):<br />ant -f samples/ant_sample/sample_pdf.xml <br />
  34. 34. Rendering Output:Required Parameters<br />There are three main parameters which are required to run the DITA-OT, regardless of the method used<br />args.input- The path and name of the input file to publish (e.g. your map) <br />transtype – The type of output to be produced.<br />Out of the box:pdf, xhtml, htmlhelp, javahelp, eclipsecontent, eclipsehelp, troff, wordrtf ordocbook<br />Plug-ins: cshelp, webworks, wordml, …<br />output.dir – The path of the output directory<br />
  35. 35. Methods of Running the Toolkit<br />An ANT build file (i.e. build_demo.xml):<br />ant –f build_demo.xml<br />Java command line – run dost.jar directly<br />java -jar lib/dost.jar /i:samples/sequence.ditamap /outdir:out /transtype:xhtml<br />Property file - send properties to build.xml.<br />Sample property file:<br />args.input=samples/sequence.ditamap<br />transtype=xhtml<br />output.dir=out<br />ANT command: <br />ant -f build.xml –propertyfile mypropertyfile.txt<br />
  36. 36. Sample ANT Build File<br />
  37. 37. Sample ANT Build File:A Closer Look<br />
  38. 38. Overview of the DITA-OT:Main Topics<br /><ul><li>Overview of the DITA-OT
  39. 39. DITA-OT Architecture
  40. 40. Rendering Outputs using Different Transtypes
  41. 41. Customizing Processing using ANT
  42. 42. Filtering Output Using DITAVAL
  43. 43. DITA-OT Resources</li></li></ul><li>Calling Multiple Targets from a Build File<br />ANT build files can be structured to run multiple targets simultaneously<br />Targets can also be nested<br />
  44. 44. Utilizing ANT Output<br />ANT Output can be useful for debugging<br />Often useful to look for the first error – later errors can be misleading<br />Can pipe output to a log file<br />ant –f hierarchy_xhtml.xml>log.txt<br />Especially useful for large / multiple ditamaps<br />Information can be added to the output.<br />Echo contents of additional variables<br />Use xsl:message to send information to the ANT output from the XSL<br />
  45. 45. Using Transtype Specific Parameters<br />For detailed documentation, see ditaotdocDITA-antscript.html.<br />Selected Examples:<br />Htmlhelp<br />args.dita.locale - The locale used for sorting indexterms. <br />Eclipsehelp<br />args.eclipse.version - The version number of the eclipse help output. <br />Javahelp<br />args.javahelp.map - The root filename of the output javahelp map file<br />
  46. 46. Overview of the DITA-OT:Main Topics<br /><ul><li>Overview of the DITA-OT
  47. 47. DITA-OT Architecture
  48. 48. Rendering Outputs using Different Transtypes
  49. 49. Customizing Processing using ANT
  50. 50. Filtering Output Using DITAVAL
  51. 51. DITA-OT Resources</li></li></ul><li>Filtering Output Using Ditaval<br />Filtering (conditional processing) based on conditional attributes:product, audience, platform, otherprops<br />The props attribute may be specialized to create additional conditional attributes<br />Use ditaval XML file to set criteria<br />By default, all topics and elements are included. <br />Ditaval file specifies which elements to exclude.<br />
  52. 52. Filtering Output Using Ditaval<br />Sample ditaval file (i.e. garage.ditaval):<br />Pass the name of the ditaval file as a parameter in the ANT build file.<br />
  53. 53. Filtering Output Using Ditaval<br />All values of a particular attribute have to be excluded for the attribute to disappear<br />Example: <step product=“prodAprodB”>If only one of the product values is excluded, the element will still appear.<br />If all of the values of any one of the attributes are excluded, the element will not appear.<br />Example:<step product=“prodA” audience=“admin”>If “admin” is excluded then the whole element is removed<br />
  54. 54. Flagging Output Using Ditaval<br />The action of a ditaval entry can be set to ‘flag’ to distinguish that element in the output.<br />The flagging style can be determined by the attributes of the prop element in the ditaval file.<br />Color – sets the text color<br />Backcolor– sets the background color<br />Style – sets the text style<br />For details, see http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/ditaval-prop.html<br />
  55. 55. Ditaval Utility<br />Developed by Suite Solutions: available for free<br />Displays all conditional attribute values used in any DITA files referenced by the chosen map<br />Displays all topics in which a particular conditional value is used<br />Choose attribute values to include using checkboxes<br />Generate ditaval file based on chosen criteria<br />Can be downloaded from: http://www.suite-sol.com/pages/resources/resources_ditaval_generation_utility.html<br />
  56. 56. Overview of the DITA-OT:Main Topics<br /><ul><li>Overview of the DITA-OT
  57. 57. DITA-OT Architecture
  58. 58. Rendering Outputs using Different Transtypes
  59. 59. Customizing Processing using ANT
  60. 60. Filtering Output Using DITAVAL
  61. 61. DITA-OT Resources</li></li></ul><li>DITA-OT Resources<br />Toolkit User Guide<br />http://www.vrcommunications.com/resources.htm<br />Toolkit Documentation<br />C:ditaotdocindex.html<br />Source Forge<br />http://sourceforge.net/projects/dita-ot<br />http://dita-ot.sourceforge.net/<br />Dita-Users email list<br />http://tech.groups.yahoo.com/group/dita-users/<br />DITA Infocenter<br />http://www.ditainfocenter.com/<br />
  62. 62. Overview of the DITA-OT:Main Topics<br /><ul><li>Overview of the DITA-OT
  63. 63. DITA-OT Architecture
  64. 64. Rendering Outputs using Different Transtypes
  65. 65. Customizing Processing using ANT
  66. 66. Filtering Output Using DITAVAL
  67. 67. DITA-OT Resources</li></li></ul><li>End of Session: Overview of the DITA Open Toolkit (Beginner Level)<br />