Down the Rabbit Hole: Getting Started with the DITA Open Toolkit

Down
the
Rabbit
Hole:
Getting
Started
with
the

DITA
Open
Toolkit

Sarah O’Keefe
Scriptorium Publishing

Wednesday, February 22, 12

Sarah
O’Keefe
❖ Founder and president, Scriptorium
Publishing
❖ Content strategy for
technical communication
❖ Interested in collision of
content, publishing, and
technology


Overview
❖ Installing the DITA Open Toolkit
❖ Generating output
❖ Customizing output


ﬂickr: themaninblue

Installing
the
OT
❖ Download from dita-ot.sourceforge.net
❖ Use version 1.5.4 for today
❖ DITA-OT1.5.4_full_easy_install_bin.zip
❖ USB drives contain DITA-OT1.5.4,
unzipped for your convenience


Best
practices
❖ Set up in top-level directory
❖ Do not use spaces in ﬁle names or
directory names
❖ Use a stable build and not the
development builds


Remember
the
command
line?
ﬂickr: johnhurn

Testing
your
installation
❖ Open a command window
❖ Navigate to your DITA OT folder
❖ Run
❖ ./startcmd.sh (UNIX)
❖ startcmd.bat (Windows)
❖ ant -f build_demo.xml


$ cd /DITA-OT1.5.4
$ ./startcmd.sh
DITA_HOME environment variable is
empty or not set

You need to edit the
startcmd.sh ﬁle.


#!/bin/sh
# This file is part of the DITA Open
Toolkit project hosted on Add this line.
SPACES MATTER!
# Sourceforge.net. See the accompanying
license.txt file for
# applicable licenses.
# (c) Copyright IBM Corp. 2006 All
Rights Reserved.

DITA_HOME="/DITA-OT1.5.4"

if [ "${DITA_HOME:+1}" != "1" ]; then
echo "DITA_HOME environment variable
is empty or not set";
exit 127;
fi
...


$ ./startcmd.sh
$ ant -f build_demo.xml
Buildfile: build_demo.xml

prompt.init:
[....]
prompt.output:
[echo]
[echo] output in the out directory
[echo]
[echo] Before rebuilding, please
delete the output or the directory.

BUILD SUCCESSFUL
Total time: 33 seconds
$ “Your OT is installed
and working.”


It
gets
better.

(No,
it
doesn’t.)

ﬂickr: wadem


Generating
output ﬂickr: cdemo

Generating
output
Theory
ant -f build.xml
   -Dargs.input=input-ditamap
   -Doutput.dir=output-folder
   -Dtranstype=transformation-type

Example
ant -f build.xml -Dargs.input=C:/DITA-
OT1.5.4/doc/userguide.ditamap
-Doutput.dir=C:/out
-Dtranstype=xhtml


Customizing
output
ﬂickr: jpockele

ﬂickr: Robobobobo

Best
practice:
Create
a
plugin

Creating
a
plugin
❖ Create a folder for the plugin
❖ Set up the plugin.xml and
conductor.xml ﬁles
❖ Verify the installation with a tiny
customization


Creating
a
folder
for
the

plugin
❖ Plugins go in the OT’s plugins directory.
❖ Naming convention is:
❖ <your domain>.<your plugin>
❖ com.scriptorium.myhtml


Set
up
plugin.xml
❖ Copy from org.dita.xhtml folder
❖ Simplify

<plugin id="com.scriptorium.myhtml">
<feature extension="dita.xsl.xhtml"
file="xsl/myxsl.xsl"/>
</plugin>


Set
up
conductor.xml
❖ Copy from org.dita.xhtml
❖ No changes


myxsl.xsl
(in
xsl
folder)
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/
XSL/Transform"
version="1.0">

<xsl:template name="gen-user-header">
<div><img src="http://www.scriptorium.com/
images/HeaderImage.png"
alt="scriptorium.com"/></div>
</xsl:template>

</xsl:stylesheet>


Integrate
your
changes

$ ant -f integrator.xml
Buildfile: integrator.xml

lax:

integrate:

BUILD SUCCESSFUL
Total time: 1 second
$


Test
the
new
plugin
❖ Same command as before

$ ant -f build.xml -Dargs.input=/DITA-
OT1.5.4/doc/userguide.ditamap -Doutput.dir=
/out -Dtranstype=xhtml


More
XSL
customization
❖ Copy template from dita2xhtml.xsl (or
referenced ﬁles) into myxhtml.xsl
❖ Modify as you like


Specifying

custom
CSS
ﬂickr: ffg

Specifying
custom
CSS
❖ Set up your own build file
❖ Fix file paths
❖ Point build file at the custom CSS you
want


Creating
a
custom
build

ﬁle
❖ In samples/ant_sample, locate
sample_xhtml.xml
❖ Put a copy in the root OT folder and
rename it: build_myxhtml.xml


Fix
the
ﬁle
paths
in

custom
build
ﬁle

<property name="sample.output.dir"
value="/out/sample"/>
<property name="css.source.dir"
location="${dita.dir}/plugins/
com.scriptorium.myhtml/css"/>


Optionally,
modify
other

settings
❖ args.input to specify the ditamap to
process
❖ args.css for the CSS ﬁle name
❖ args.csspath for the CSS directory path


Run
custom
build
and

admire
the
results ﬂickr: tompeters1994

Run
custom
build
and

admire
the
results
❖ Arguments are not needed if you
customized the build ﬁle with your
exact settings

$ ant -f build_myxhtml.xml -Dargs.input=/
Users/okeefe/Documents/CSinTC/csintc.ditamap
-Doutput.dir=/out -Dtranstype=xhtml


ﬂickr: jpockele

Beyond
the
basics


You
will
need…
❖ XHTML or HTML5
❖ CSS
❖ Apache Ant
❖ XSLT
❖ XML DTDs
❖ XSL-FO (for PDF customization)


Take
care
of

formalities

ﬂickr: Carly & Art

Keep
changes
in
plugins

folder
and
custom
build
ﬁles
❖ Do not change core Open Toolkit
❖ Use code comments extensively


Document
your
changes!

amazon.com


Q
&
A
ﬂickr: gracewong

Visit
our
booth…
❖ Sarah O’Keefe
❖ okeefe@scriptorium.com
❖ Twitter: @sarahokeefe
❖ www.scriptorium.com
❖ BTW, we’re hiring.
❖ Also, we have chocolate.


Down the Rabbit Hole: Getting Started with the DITA Open Toolkit

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie Down the Rabbit Hole: Getting Started with the DITA Open Toolkit

Ähnlich wie Down the Rabbit Hole: Getting Started with the DITA Open Toolkit (20)

Mehr von Scriptorium Publishing

Mehr von Scriptorium Publishing (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Down the Rabbit Hole: Getting Started with the DITA Open Toolkit