dita open toolkit: open the gates to structured content
TRANSCRIPT
© 2016 VMware Inc. All rights reserved.
DITA Open ToolkitOpen the Gates to Structured Content
Iliana Kostova
Oct 25th, 2016
Agenda
1. Introduction to the DITA Open Toolkit
2. DITA Open Toolkit Architecture
3. Exercise: Generating Content in Several Output Formats
a. Background
b. Action
4. Exercise: Interesting DITA Techniques
a. Background
b. Action
5. Exercise: Example DITA OT Repository
6. Enterprise CMS vs DITA OT
7. Summary
2
3
Introduction to the DITA Open Toolkit
5
HTML5
DITA Content Management in a Nutshell
XHTML PDF
Word
Storage
Version control
Generation
engine
Publishing
channel
Infrastructure
6
HTML5
DITA Toolkit in the Content Management Process
XHTML PDF
Word
DITA OT
WYSIWYG
Editor
Doc Web
site
7
Output Generation Engine for DITA
What is the DITA Open Toolkit?
8
–First steps in DITA
–New features in the DITA specification
–In production at a lower cost
–How a Content Management System (CMS) works
When Would I Use the DITA Open Toolkit?
9
–Open source (free)
–Easy to download and run
–Easy to configure
–No need for an enterprise CMS
Why Would I Use the DITA Open Toolkit?
10
– Web site: http://www.dita-ot.org/
– GitHub project location:
https://github.com/dita-ot
– GitHub download location:
https://github.com/dita-ot/dita-ot/releases/
Download Location
11
–Distribution ZIP package – extract and use; includes XLST files
–Source ZIP package – Java support for XML processing and output generation
–WYSIWYG Editors
Packaging
12
Architecture
13
HTML5
DITA Toolkit in the Content Management Process
XHTML PDF
Word
DITA OT
WYSIWYG
Editor
Validation and Parsing
Transform
XML
Parser
XML
Preprocessor
and
XSLT/Java
Engine
Apache
Ant
14
DITA Open Toolkit Modules
DITA OT
Validation and Parsing
Transform
XML
Parser
XML
PreprocessorApache
Ant
Filter, pull conref’s, generate
related links
Check if the XML docs
are valid against the
DITA standard
Orchestrate
XSLT/Java
Engine
Apply the rules from XSLT
files to generate output
15
DITA Open Toolkit Plug-Ins
DITA OT
Validation and Parsing
Transform
XML
Parser
XML
PreprocessorApache
Ant
XSLT/Java
Engine
HTML5
XHTML PDF
Word
New doc type
(new specialization
+ new xslt rules)
New outyput type
(new xslt rules +
new build target)
Markdown
16
Exercises
17
Introduction to the Exercises
18
Exercise 1: Running DITA OT
CONFIDENTIAL19
Exercise 1: Running DITA OT - Objectives
• Learn how to generate consumable content
• Learn more about different output support
• Learn how to configure output generation
Exercise 1: Running DITA OT - Background
• Prerequisites
– Windows or Linux OS
– Java Development Kit (JDK) 7 or later
– DITA OT extracted
• Command
– dita command (new)
– Calling Ant on a build.xml file (add command line)
– From your DITA WYSIWYG editor
• Input arguments
– Input DITA map or DITA topic
– Transform (output) type
– Output folder
– Additional arguments (common and output-specific)
20
Exercise 1: Running DITA OT - Background
bin/dita
-input input-file
-format format
-output transformtype
-Doption1=value1 -Doption2=value2
21
Exercise 1: Running DITA OT - Action
• Generate HTML5 and PDF output for a DITA map in a special folder
– Groups
• HTML with CSS
• HTML with a TOC tree
– Use the stickies for the dita command line according to the output
– Use the handouts for help
22
Exercise 1: Running DITA OT
23
Exercise 2: Interesting DITA XML Features
24
Exercise 2: Interesting DITA XML Features -Objectives
• Learn how to test advanced features that are purely in DITA XML
• Learn how to test features that require additional processing
16
Exercise 2: Interesting DITA XML Features -Background
• Nesting topics
– Of the same type or of mixed types?
– Manually
– Automatic – chunk attribute for topicref’s in maps
26
Exercise 2: Interesting DITA XML Features -Background
• Keys
– Purpose – use location-agnostic reference to a topic or a piece of topic in links and conref (pull and push)
– Traditional conref is location-aware:step conref=“<target dita
file/object>#<topic_id>/<element_id>”
– You define a key in a map and use in topics without knowledge of the location
27
Exercise 2: Interesting DITA XML Features -Background
• Conditions
– Leave out, include or change content if a condition is true
– Conditions – platform, audience, product, rev, otherprops
28
– Conditional filtering - .ditaval file
Exercise 2: Interesting DITA XML Features -Action
• Generate from a topic made of different nested types
• Reuse and link using keys
– What elements do you need?
– Pull the content
• Use a condition to generate output for Linux admins
– What elements do you need?
29
Exercise 2: Interesting DITA XML Features
30
Exercise 3: Example Repository
31
Exercise 3: Example Repository - Objectives
• Learn how to plan a repository for source control systems (SCMs)
16
Exercise 3: Example Repository - Background
• Share the same repository as engineers
– Benefit from advanced versionins and branching of SCMs
– Rely on the same build team as engineers
– Automate regular builds reusing the setup for the engineers (e.g. use the DITA OT plug-in for Maven)
– Enable engineers to access and build the latest doc by using a familiar toolchain
16
Exercise 3: Example Repository - Action
• Create a repository structure to support several documentation sets
– Use the stickies to
• Include the required folders handed by Iliana
• Name the rest of the folders
• Model the tree
34
Exercise 3: Example Repository - Action
• Examine an example structure of a documentation set
16
dita-ot-home-dir
module1-docs
bin lib plugins
build outputdita
html
generate-output.bat
filter.ditaval
output-log.log
module1.ditamap
concepts
tasks
. . . . . .
. . .
module2-docs
. . .
xsl
Exercise 3: Example Repository
36
Enterprise CMS vs DITA OT
Enterprise CMS DITA Open Toolkit
Pricey Free
Dependence on an external team for updates with
new features
Ability to download and use right away
Professional look-and-feel of the output and
version control
Need to customize it but can be easily integrated
in traditional version control systems like Perforce
and Git and build systems like Maven
You concentrate on the authoring part You need to do some short learning first
Heavy infrastructure setup process You only need a version control system and space
on your computer
. . . . . .
37
Takeaways
• Easy to get started
• Easy to experiment with DITA and single-sourcing
• Easy to pack and integrate in the release
• Easy to customize
38
Useful DITA OT Resources
• DITA OT Home Page
• DITA OT Groups
– Yahoo
• DITA Specification
• Scriptorium, Oxygen
• Apache Ant Project
39
Your opinion is important to us! Please tell us what you thought of the lecture. We look forward to your feedback via smartphone or tablet under
http://in31.honestly.deor scan the QR code
The feedback tool will be available even after the conference!
Thank you!
41