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

Down the Rabbit Hole:Getting Started with the

DITA Open Toolkit

Sarah O’KeefeScriptorium Publishing

Wednesday, February 22, 12

Sarah O’Keefe

❖ Founder and president, Scriptorium Publishing

❖ Content strategy fortechnical communication

❖ Interested in collision ofcontent, publishing, andtechnology


Overview

❖ Installing the DITA Open Toolkit

❖ Generating output

❖ Customizing output


flickr: themaninblueWednesday, February 22, 12

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 file names or directory names

❖ Use a stable build and not the development builds


Remember the command line?flickr: 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.shDITA_HOME environment variable is empty or not set

You need to edit the startcmd.sh file.


#!/bin/sh# This file is part of the DITA Open Toolkit project hosted on # 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...

Add this line.SPACES MATTER!


$ ./startcmd.sh$ ant -f build_demo.xmlBuildfile: 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 SUCCESSFULTotal time: 33 seconds$ “Your OT is installed

and working.”


It gets better.

flickr: wadem

(No, it doesn’t.)


flickr: cdemoGenerating output


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

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

Generating outputTheory

Example


Customizing outputflickr: jpockele


Best practice: Create a plugin

flickr: Robobobobo


Creating a plugin

❖ Create a folder for the plugin

❖ Set up the plugin.xml and conductor.xml files

❖ 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


<?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>

myxsl.xsl (in xsl folder)


http://www.w3.org/1999/XSL/Transform




http://www.scriptorium.com/images/HeaderImage.png




Integrate your changes

$ ant -f integrator.xmlBuildfile: integrator.xml

lax:

integrate:

BUILD SUCCESSFULTotal 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 files) into myxhtml.xsl

❖ Modify as you like


Specifying custom CSS

flickr: 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 file❖ In samples/ant_sample, locate

sample_xhtml.xml

❖ Put a copy in the root OT folder and rename it: build_myxhtml.xml


Fix the file paths in custom build file

<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 file name

❖ args.csspath for the CSS directory path


Run custom build and admire the results

flickr: tompeters1994


Run custom build and admire the results❖ Arguments are not needed if you

customized the build file with your exact settings

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


Beyond the basicsflickr: jpockele


You will need…

❖ XHTML or HTML5

❖ CSS

❖ Apache Ant

❖ XSLT

❖ XML DTDs

❖ XSL-FO (for PDF customization)


Take care of formalities

flickr: Carly & ArtWednesday, February 22, 12

Keep changes in plugins folder and custom build files

❖ Do not change core Open Toolkit

❖ Use code comments extensively


Document your changes!

amazon.com


Q & Aflickr: gracewong


Visit our booth…

❖ Sarah O’Keefe

❖ [email protected]

❖ Twitter: @sarahokeefe

❖ www.scriptorium.com

❖ BTW, we’re hiring.

❖ Also, we have chocolate.


mailto:[email protected]

mailto:[email protected]

http://www.scriptorium.com

http://www.scriptorium.com

Date post:	12-May-2015
Category:	Technology
Upload:	scriptorium-publishing
View:	1,583 times
Download:	2 times

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

Technology