down the rabbit hole: getting started with the dita open toolkit
Post on 12-May-2015
1.586 Views
Preview:
DESCRIPTION
TRANSCRIPT
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
Wednesday, February 22, 12
Overview
❖ Installing the DITA Open Toolkit
❖ Generating output
❖ Customizing output
Wednesday, February 22, 12
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
Wednesday, February 22, 12
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
Wednesday, February 22, 12
Remember the command line?flickr: johnhurn
Wednesday, February 22, 12
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
Wednesday, February 22, 12
$ cd /DITA-OT1.5.4$ ./startcmd.shDITA_HOME environment variable is empty or not set
You need to edit the startcmd.sh file.
Wednesday, February 22, 12
#!/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!
Wednesday, February 22, 12
$ ./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.”
Wednesday, February 22, 12
It gets better.
flickr: wadem
(No, it doesn’t.)
Wednesday, February 22, 12
flickr: cdemoGenerating output
Wednesday, February 22, 12
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
Wednesday, February 22, 12
Customizing outputflickr: jpockele
Wednesday, February 22, 12
Best practice: Create a plugin
flickr: Robobobobo
Wednesday, February 22, 12
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
Wednesday, February 22, 12
Creating a folder for the plugin❖ Plugins go in the OT’s plugins directory.
❖ Naming convention is:
❖ <your domain>.<your plugin>
❖ com.scriptorium.myhtml
Wednesday, February 22, 12
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>
Wednesday, February 22, 12
Set up conductor.xml
❖ Copy from org.dita.xhtml
❖ No changes
Wednesday, February 22, 12
<?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)
Wednesday, February 22, 12
Integrate your changes
$ ant -f integrator.xmlBuildfile: integrator.xml
lax:
integrate:
BUILD SUCCESSFULTotal time: 1 second$
Wednesday, February 22, 12
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
Wednesday, February 22, 12
More XSL customization
❖ Copy template from dita2xhtml.xsl (or referenced files) into myxhtml.xsl
❖ Modify as you like
Wednesday, February 22, 12
Specifying custom CSS
flickr: ffg
Wednesday, February 22, 12
Specifying custom CSS
❖ Set up your own build file
❖ Fix file paths
❖ Point build file at the custom CSS you want
Wednesday, February 22, 12
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
Wednesday, February 22, 12
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"/>
Wednesday, February 22, 12
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
Wednesday, February 22, 12
Run custom build and admire the results
flickr: tompeters1994
Wednesday, February 22, 12
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
Wednesday, February 22, 12
Beyond the basicsflickr: jpockele
Wednesday, February 22, 12
You will need…
❖ XHTML or HTML5
❖ CSS
❖ Apache Ant
❖ XSLT
❖ XML DTDs
❖ XSL-FO (for PDF customization)
Wednesday, February 22, 12
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
Wednesday, February 22, 12
Document your changes!
amazon.com
Wednesday, February 22, 12
Q & Aflickr: gracewong
Wednesday, February 22, 12
Visit our booth…
❖ Sarah O’Keefe
❖ okeefe@scriptorium.com
❖ Twitter: @sarahokeefe
❖ www.scriptorium.com
❖ BTW, we’re hiring.
❖ Also, we have chocolate.
Wednesday, February 22, 12
top related