Your SlideShare is downloading. ×
DITA Quick Start Webinar Series: Getting Started with the DITA Open Toolkit
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

DITA Quick Start Webinar Series: Getting Started with the DITA Open Toolkit

1,089
views

Published on

Presenter: Adena Frazer, Senior Developer, Suite Solutions …

Presenter: Adena Frazer, Senior Developer, Suite Solutions
Abstract:
In this webinar you will learn about the DITA Open Toolkit architecture and acquire the basics of running and benefiting from the DITA-OT. This webinar will guide you in:
• Leveraging your DITA content in a variety of output formats, such as PDF, XHTML, and HTML Help
• Customizing your DITA content processing
• Filtering your output for different audiences

Published in: Technology

0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,089
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
3
Comments
0
Likes
1
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. Getting Started with the DITA Open Toolkit Adena Frazer, Suite Solutions
  • 2. Who am I? Adena Frazer • Background in Computer Science and Education • Early and senior member of the Suite Solutions team • Given many public and private training seminars over the past five years • Extensive expertise implementing DITA and CMS solutions for a wide variety of organizations • Responsible for internal training and mentoring for developers at Suite Solutions • Help companies get it right the first time
  • 3. About Suite Solutions Our Vision: Enable companies to engage their customers by providing quick access to relevant information • Help companies get it right the first time • XML-based Authoring/Publishing Solutions • Enterprise Intelligent Dynamic Content: SuiteShare • Consultancy, Systems Integration, Application Development • Cross-Industry Expertise • High Tech, Aerospace & Defense • Healthcare, Discrete Manufacturing • Blue Chip Customer Base • Hundreds of Person Years of Experience on Staff
  • 4. Main Topics • • • • • • Overview of the DITA-OT DITA-OT Architecture Rendering Output with the DITA-OT Customizing Processing using ANT Filtering Output Using DITAVAL DITA-OT Resources
  • 5. Overview of the DITA-OT DITA Open Toolkit – Open source tool that processes DITA source content and produces output in a variety of formats. Processing tasks include: • Validation • Checks that files are valid DITA • Checks referenced files and links • Resolves references and links • topicrefs, conrefs, xrefs, keyrefs, conkeyrefs • Performs conditional publishing • Includes or excludes topics and elements based on conditional attributes: product, audience, platform, otherprops
  • 6. Overview of DITA-OT • • Dynamically generates links • Parent/child links • Related links • TOC • Index • Bookmarks Renders or compiles the final output using the relevant style sheets: • HTML Formats: XHTML, HTML Help, Eclipse Help, JavaHelp • Docbook, ODT, RTF, TROFF • FO to PDF  Merges files into one document  Calls a PDF rendering engine
  • 7. Plug-ins • • • • The DITA-OT uses a plug-in mechanism to allow users to add and remove components in a modular way. Recent releases of the DITA-OT have moved existing code to separate plug-ins. Plug-ins are located in the DITA-OTplugins directory. • Includes many files that used to be located in the demo folder. For details about how plug-ins are implemented in the DITA-OT, see the Developing Plug-ins and Working with FO plug-in Extension Points webinar • Located at http://www.suite-sol.com/pages/services/ services_training_dita_ot_training_webinars_recorded.html
  • 8. DITA-OT 1.8 • The latest version of the DITA-OT is 1.8 (M2) • Released on September 17, 2013 New Features Include: • Additional validation in the preprocessing step • Bundled FOP has been updated from version 1.0 to 1.1. • Code cleanup and reorganization • Removed deprecated code and ANT properties • Updated existing code. • Moved a number of style sheets to plug-in specific folders • A variety of bug fixes and new features • For more details, see DITA-OT1.8.M2relnotes.html or the DITA-OT Release History section of the DITA-OT User Guide
  • 9. Main Topics  • • • • • Overview of the DITA-OT DITA-OT Architecture Rendering Output with the DITA-OT Customizing Processing using ANT Filtering Output Using DITAVAL DITA-OT Resources
  • 10. DITA-OT Architecture DOST.ja r XML Parsing and Validation XSL Transforms Apache ANT XSL style sheets XML Parser XSLT Engines •XERCES •SAXON •XALAN •Resolver.jar •Icu4j.jar •Fop.jar •Batik.jar
  • 11. Apache ANT • • • • • Build management tool similar to Make files from DOS – manages targets and dependencies Used primarily by the Java community Used as the control program for the DITA-OT workflow ANT is used for common development tasks such as • Running the Toolkit • Creating plug-ins • HTML customization Located in ditaottoolsant
  • 12. Xerces • • Xerces is a collection of software libraries created by Apache Used for parsing, validating, serializing and manipulating XML (http://en.wikipedia.org/wiki/Xerces) • Located in ditaotlibxercesImpl.jar XML Parsing and Validation XML Parser •XERCES
  • 13. DOST.jar • • • • DOST – DITA Open Source Toolkit Contains all of the JAVA code unique to the Toolkit as a whole • JAVA is a more general purpose programming language than ANT or XSLT • Some code is written in JAVA to improve performance. Code is compiled • Source needs to be downloaded separately • When the source is changed, the jar needs to be recompiled. Located in the ditaotlib directory
  • 14. Additional JAVA Components • • Additional Java libraries that are packaged with the Toolkit include: • Resolver.jar  Resolves file references using catalog files • Icu4j.jar  International Components for Unicode for Java - used for internationalization • Fop.jar  Formatting Object Processor - Apache open source application that converts XSL Formatting Objects to PDF • Batik.jar  Graphics library used by FOP Located in ditaotlib and ditaotpluginsorg.dita.pdf2fop
  • 15. XSLT Engines Saxon • Saxon is an XSLT and XQuery processor created by Michael Kay. • Saxon version 9 (and up) implements the XSLT 2.0 specifications and can process XSLT 1.0 files as well. • This version ships with the DITA-OT • Located in ditaotlibsaxon Xalan • XSLT and XPath Processor from the Apache Software Foundation. • It has some bugs and does not support XSLT2. • It was initially packaged with the DITA-OT (through version 1.4.2) due to licensing issues with Saxon. Saxon is the recommended XSLT processor to be used with the DITA-OT.
  • 16. DITA-OT Architecture DOST.ja r XML Parsing and Validation XSL Transforms Apache ANT XSL style sheets XML Parser XSLT Engines •XERCES •SAXON •XALAN •Resolver.jar •Icu4j.jar •Fop.jar •Batik.jar
  • 17. Main Topics   • • • • Overview of the DITA-OT DITA-OT Architecture Rendering Output with the DITA-OT Customizing Processing using ANT Filtering Output Using DITAVAL DITA-OT Resources
  • 18. Required Parameters • Three main parameters are required to run the DITA-OT, regardless of the method used: • args.input - The path and name of the input file to publish • transtype – The output format to be produced. Transtypes Available by Default docbook javahelp rtf eclipsehelp legacypdf troff eclipsecontent odt xhtml htmlhelp pdf • output.dir – The path of the output directory
  • 19. Rendering Output • Always open the cmd window by double clicking on ditaotstartcmd.bat or running ditaotstartcmd.sh to make sure that the required variables are properly set • Run ditaotbuild_demo.xml to easily test installation • Type: ant –f build_demo.xml • Follow the instructions • Use the command-line tool. • Supports a subset of the ANT parameters • Type: java -jar lib/dost.jar /i:samples/sequence.ditamap /outdir:out /transtype:xhtml
  • 20. Rendering Output • Use a property file to send properties to build.xml. • Sample property file: args.input=samples/sequence.ditamap transtype=xhtml output.dir=out • ANT command:  ant -f build.xml –propertyfile mypropertyfile.txt • Use ANT build scripts • Samples and templates can be found in the ditaot/samples/ant_sample directory. • Type: ant -f samples/ant_sample/sample_pdf.xml • This is the recommended method for running the Toolkit.
  • 21. Sample ANT Build File • Concise version of ditaotsamplesant_samplesample_pdf.xml: <project name="sample_pdf" default="samples.pdf" basedir="."> <property name="dita.dir" location="${basedir}/../.."/> <target name="samples.pdf"> <ant antfile="${dita.dir}/build.xml"> <property name="args.input” location="${dita.dir}/samples/sequence.ditamap"/> <property name="output.dir" location="${dita.dir}/out/samples/pdf"/> <property name="transtype" value="pdf"/> </ant> </target> </project>
  • 22. Main Topics    • • • Overview of the DITA-OT DITA-OT Architecture Rendering Output with the DITA-OT Customizing Processing using ANT Filtering Output Using DITAVAL DITA-OT Resources
  • 23. Using ANT Parameters • • • • • The DITA-OT provides an extensive list of built in ANT parameters that can be used to control the DITA-OT processing Parameters can be relevant to • All transtypes • HTML based transtypes • Specific transtypes. For a detailed reference of available parameters, see pages 57-64 of the DITA-OT User Guide Custom parameters can also be added to the DITA-OT processing and passed in from ANT. Optional parameters are passed into the DITA-OT using the same format as the required parameters. For example: <property name=“clean.temp" value=“no"/>
  • 24. Using ANT Parameters • Selected ANT Parameters: Name Description Allowed Values Default Value args.draft Specifies whether the content of <draft-comment> and <required-cleanup> elements is included in the output. yes, no no clean.temp Specifies whether the DITA-OT deletes the files in the temporary directory after it finishes a build. yes, no yes validate Specifies whether the DITA-OT validates the content. true, false true args.rellinks Specifies which links to include in the output. • none – No links are included. • all – All links are included. • nofamily – Parent, child, next, and previous links are not included none, all, nofamily none
  • 25. Additional Processing with ANT • ANT can be used for a wide variety of custom processing tasks • For example, the sample ANT build files that are shipped with the Toolkit use ANT to delete old output before new output is generated: <target name="samples.pdf" " depends="clean.samples.pdf"> <!--Call to DITA-OT goes here--> </target> <target name="clean.samples.pdf" > <delete dir="${dita.dir}/out/samples/pdf"/> </target>
  • 26. Calling Multiple Targets • ANT build files can be structured to run multiple targets with one call <target name="all" depends=“render_xhtml, render_pdf"></target> <target name=“render_xhtml"> <!--Call to XHTML DITA-OT processing goes here --> </target> <target name=“render_pdf" > <!-- Call to PDF DITA-OT processing goes here --> </target> • Targets can also be nested
  • 27. Debugging using ANT • • • ANT output can be useful for debugging • Often useful to look for the first error – later errors can be misleading Can pipe output to a log file • ant –f sample_pdf.xml>log.txt • Especially useful for builds with a large amount of output Information can be added to the output. • Values of variables can be echoed to the output • Use xsl:message to send information to the ANT output from the XSL
  • 28. Main Topics     • • Overview of the DITA-OT DITA-OT Architecture Rendering Output with the DITA-OT Customizing Processing using ANT Filtering Output Using DITAVAL DITA-OT Resources
  • 29. Filtering Output Using DITAVAL • • • The DITA-OT performs filtering (conditional processing) based on conditional attributes: • product • audience • platform • otherprops The props attribute may be specialized to create additional conditional attributes Use the DITAVAL XML file to set criteria • By default, all topics and elements are included. • DITAVAL file specifies which elements to exclude.
  • 30. Filtering Output Using DITAVAL • Sample DITAVAL file (e.g. garage.ditaval): <?xml version="1.0" encoding="UTF-8"?> <val> <prop att="product" val="ford" action="include"></prop> <prop att="product" val="honda" action="exclude"></prop> </val> • Pass the name of the DITAVAL file as a parameter in the ANT build file. <property name="dita.input.valfile“ value="${dita.dir}/garage.ditaval" />
  • 31. Filtering Output Using DITAVAL • • All values of a particular attribute have to be excluded for the attribute to disappear • Example: <step product=“ford honda”> If only one of the product values is excluded, the element will still appear. If all of the values of any one of the attributes are excluded, the element will not appear. • Example: <step product=“ford” audience=“admin”> If “admin” is excluded then the whole element is removed
  • 32. Flagging Output Using DITAVAL • • The action of a DITAVAL entry can be set to „flag‟ to distinguish that element in the output. The flagging style can be determined by the attributes of the prop element in the DITAVAL file. • Color – sets the text color • Backcolor – sets the background color • Style – sets the text style <prop att="product" val="volkswagon" action="flag" backcolor="pink" style="italics"></prop> • color="red" For details, see http://ditaspec.suite-sol.com/langref/ditaval-prop.html
  • 33. DITAVAL Utility • • • • • • Developed by Suite Solutions: available for free Displays all conditional attribute values used in any DITA files referenced by the chosen map Displays all topics in which a particular conditional value is used Choose attribute values to include using checkboxes Generate DITAVAL file based on chosen criteria Can be downloaded from: http://www.suite-sol.com/pages/resources/ resources_ditaval_generation_utility.html
  • 34. Main Topics      • Overview of the DITA-OT DITA-OT Architecture Rendering Output with the DITA-OT Customizing Processing using ANT Filtering Output Using DITAVAL DITA-OT Resources
  • 35. DITA-OT Resources • • • • • DITA-OT User Guide • ditaotdochtmlindex.html • ditaotdocuserguide.pdf Source Forge • http://sourceforge.net/projects/dita-ot • http://dita-ot.sourceforge.net/ Dita-Users email list • http://tech.groups.yahoo.com/group/dita-users/ DITA-XML • http://dita.xml.org/wiki/the-dita-open-toolkit DITA Specification • http://ditaspec.suite-sol.com/Home_ditaspec.html
  • 36. Main Topics       Overview of the DITA-OT DITA-OT Architecture Rendering Output with the DITA-OT Customizing Processing using ANT Filtering Output Using DITAVAL DITA-OT Resources
  • 37. Hmmm, this looks interesting… For additional information, contact us: Adena Frazer solutions@suite-sol.com U.S. Office (609) 360-0650 EMEA Office +972-2-993-8054 www.suite-sol.com Please take a moment and follow us on LinkedIn: http://www.linkedin.com/company/527916
  • 38. Next Steps… UPCOMING WEBINARS IN THE DITA QUICK START SERIES: • COMING UP NEXT: System Architecture of a Basic DITA Toolset Tuesday, October 29 2PM EDT • Migrating to DITA: Building a Project Plan • Migrating to DITA: Defining Your Style Sheet Requirements • Migrating to DITA: Defining Your Conversion Requirements • Migrating to DITA: Defining Your Translation Requirements • Please take a moment and follow us on LinkedIn: http://www.linkedin.com/company/527916