Are you new to the world of DITA? Have you read the various DITA primers available? If so, you are probably now raring to play with DITA.

Ahh.. writer's block! How do you get started? What and where are you supposed to write? A starting point into a small DITA project would be nice.

Here is a DITA project starter kit that you can use to experiment with DITA, create topics and try building various outputs. The DITA project starter kit contains the following:

• Sample concept, task and reference topic files and a ditamap

• Ant scripts to help you build your first DITA project

Follow the steps below to setup your environment for DITA and get started!

 

Setting up your DITA Environment

If this is the first time you are working with DITA, and have not setup the DITA Open Toolkit, follow the steps below. Otherwise, skip to the section titled "Starting a new DITA Based Project" .

• Download and install Java SE (> version 5.0. I have been using 6.0 without problems so far).
• Download and install the full package distribution of the latest DITA Open Toolkit (latest at this time is version 1.4.2.1).
• Edit DITA-OT1.4.2.1/startcmd.bat and set JAVA_HOME and modify PATH environment variables. For example,

 

set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_06
set PATH=%DITA_DIR%tools\ant\bin;%JAVA_HOME%\bin;%PATH%

 

 

• Run DITA-OT1.4.2.1/startcmd.bat to open a DITA command window. These scripts set a few DITA specific environment variables. (Note: If using Unix, you may need to correct startcmd.sh to use DITA_DIR instead of DITA_HOME, and also add the Java related variables).
• In the DITA command window, make sure DITA_DIR and ANT_HOME environment variables are set.
• Type java -version to make sure that Java has been setup properly.

 

Starting a new DITA Based Project

• Download and unzip the attached NewDITAProjectSource.zip to a local folder. This zip file has the following folders:

• Edit NewDITAProjectSource/runbuild.bat or NewDITAProjectSource/runbuild.sh (depending on your environment).
• Change the parameters specified in the runbuild file to make them specific to your project (detailed information can be found in the runbuild file)
• In your DITA command window, change directory to NewDITAProjectSource and execute the command runbuild dita2xhtml.
• If all goes well, you should see the following messages. The NewDITAProjectOutput directory should be created at the location specified previously.

   

  Buildfile: ant_scripts\newDITAProject_all.xml [echo] [echo] Building project. [echo] Processing started... Initialize log directory and file name... Validate and init input arguments... [echo] ***************************************************************** [echo] * basedir = D:\bins\DITA-OT1.4.2.1\ [echo] * dita.dir = D:\bins\DITA-OT1.4.2.1 [echo] * input = D:\users\sk\ws\NewDITAProjectSource/NewDITAProject.ditamap [echo] * transtype = xhtml [echo] * tempdir = D:\users\sk\ws\NewDITAProjectOutput/temp [echo] * outputdir = D:\users\sk\ws\NewDITAProjectOutput/xhtml [echo] * extname = .xml [echo] * clean.temp = ${clean.temp} [echo] * xslt.parser = XALAN [echo] ***************************************************************** Preprocessing started... Clean temp directory... .... .... Build XHTML output from inner dita topics... Build XHTML output from outer dita topics... Processing ended. BUILD SUCCESSFUL Number of Fatals : 0 Number of Errors : 0 Number of Warnings : 0 Total time: 3 seconds Log file 'NewDITAProject_xhtml.log' was generated successfully in directory

 

• View NewDITAProjectOutput/xhtml/index.html in a web browser and see xhtml output

If you have come this far, High Five!!

Creating Custom Content

Follow the steps below to further customize this project template to your needs.

• Decide on a project name. For the sake of this example, assume the new name is CoolTech.
• Rename the NewDITAProjectSource directory to CoolTechSource
• Edit CoolTechSource/runbuild.bat. Search and replace the string "NewDITAProject" with "CoolTech". You should now have -Dprojdir=somepath\CoolTechSource -Doutdir=somepath\CoolTechOutput -Dmap=CoolTech.ditamap -f ant_scripts\CoolTech_all.xml
• Rename the file CoolTechSource\NewDITAProject.ditamap to CoolTechSource\CoolTech.ditamap
• Rename CoolTechSource\ant_scripts\newDITAProject_all.xml to CoolTechSource\ant_scripts\CoolTech_all.xml
• Edit CoolTechSource\ant_scripts\CoolTech_all.xml. Change <project name="newditaproject" default="xhtml">

  to

  <project name="cooltech" default="xhtml">
• From your DITA command window, execute the command runbuild dita2xhtml and verify output.
• Add or edit the included topics and map using a DITA editor, any XML editor, or even vi (depending on your comfort level). Build the source to see your changes.

 

Reference

DITA Open Toolkit User Guide (useful information on using and troubleshooting DITA OT)

DITA Language Specification (understand how and where DITA tags should be used)

DITA Architectural Specification (more technical stuff)

 

 

 

 

 

 

Attachment	Size
NewDITAProjectSource.zip	53.09 KB