To boldly go where no tech writer has gone before (one can dream, right?)

The World’s Smallest DITA Project Part 2: Let’s do it!

(This post is part of the Learn DITA on Your Own series.)

Now that you’ve installed and tested the tools, the fun can begin :)

The World’s Smallest DITA Project is a simple map that will contain a single topic. The objective of today’s exercise is not to cover all the DITA concepts but rather to go through a complete cycle of creating a DITA topic, adding it to a DITA map, and converting the DITA map to a PDF file.

The project will be stored in a directory called Worlds_smallest_dita_project.

Create a topic


First, let’s create a topic. As we’ve seen, there are three types of topics: concept, task, and reference. For this project, we’ll create a topic of type concept.

To create a topic:

  1. Using Windows Explorer, create the directory that will contain your project, directly under the C:\ directory, and name it Worlds_smallest_dita_project.
  2. Start Notepad++.
  3. Select File–>New.
  4. Select File–>Save As.
  5. Navigate to the C:\Worlds_smallest_dita_project directory and save the file as wsdp_small_is_beautiful.xml.
  6. Copy the following header to the wsdp_small_is_beautiful.xml document:
    <!--?xml version="1.0" encoding="utf-8"?-->
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
     "C:\DITA-OT1.8.M2\dtd\technicalContent\dtd\concept.dtd">
    

    The first line specifies that this is an XML document. The second and third lines indicate that this document is of type concept and should be validated against the concept.dtd DTD file. A DTD file can be seen as the dictionary that defines how a DITA document can be formed.

    As you can see in the example above, the third line provides an absolute path to the concept.dtd file that is packaged with the DITA OT. In a real project, you would not provide the absolute path to the DTD, as we’re doing here, since you want to be able to move your project files. You would instead declare a public ID in an XML catalog that basically says: “When I talk about the concept.dtd file, here’s where to find it”. But to keep this project easy (it is, after all, the World’s Smallest DITA Project), we’ll include an absolute path.

  7. Edit the third line so that it points to the concept.dtd file provided with your DITA OT.
    For example, if you installed the DITA OT in the C:\DITA-OT1.8 directory, change the third line to the following:

    <!--?xml version="1.0" encoding="utf-8"?-->
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
     "C:\DITA-OT1.8\dtd\technicalContent\dtd\concept.dtd">
    
  8. Add the following line at the end of the file:
    <concept id="wsdp_topic_1" xml:lang="en-us">
    

    The <concept> element is the top-level element of a topic of type concept. In the example above, we specify an ID for this topic (“wsdp_topic_1″) so that we can create cross-references to it. We also specify that it’s written in US English.

  9. Specify the title of the document by adding the following line at the end of the file:
       <title>Small is beautiful</title>
    
  10. Specify a short description for this topic by adding the following lines:
    <shortdesc><i>Small is beautiful</i> is the title of a book written
        by Ernst Friedrich "Fritz" Schumacher.</shortdesc>
    

    A <shortdesc> is a special DITA element used to provide a short description of the topic. The short description is a very interesting element that can also be used to preview the content of a link or for searching when the document is generated.

  11. Finally, add the following line to close the <concept> element:
    </concept>
    

    The file should now look as follows:

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
     "C:\DITA-OT1.8.M2\dtd\technicalContent\dtd\concept.dtd">
    <concept id="wsdp_topic_1" xml:lang="en-us">
       <title>Small is beautiful</title>
       <shortdesc><i>Small is beautiful</i> is the title of a book written
           by Ernst Friedrich "Fritz" Schumacher.</shortdesc>
    </concept>
    
  12. Select  File–>Save.

Now let’s create a DITA map.

Create a map


To create a map:

  1. In Notepad++, select File–>New.
  2. Select  File–>Save As.
  3. Navigate to the C:\Worlds_smallest_dita_project directory and save the file as worlds_smallest_dita_project.ditamap‏.
    Note: Make sure that there is no extra space after the file name before you click Save.
  4. Copy the following header to the worlds_smallest_dita_project.ditamap‏ document:
    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
     "C:\DITA-OT1.8.M2\dtd\technicalContent\dtd\map.dtd">
    

    As with the topic file, the first line specifies that this is an XML document. The second and third lines indicate that this document is of type map and should be validated against the map.dtd DTD file.

  5. Edit the third line so that it points to the map.dtd file provided with your DITA OT.
    For example, if you installed the DITA OT in the C:\DITA-OT1.8 directory, change the third line to the following:

    <!--?xml version="1.0" encoding="utf-8"?-->
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
     "C:\DITA-OT1.8\dtd\technicalContent\dtd\map.dtd">
    
  6. Add the following line at the end of the file:
    <map title="World's Smallest DITA Project">
    

    The <map> element is the top-level element of a map. In the example above, we also specify the title of the map in the title attribute of the map element.

  7. Add a reference to the topic “Small is beautiful” by adding the following line:
    <topicref href="wsdp_small_is_beautiful.xml" type="concept"/>
    

    This element indicates that the wsdp_small_is_beautiful.xml file is now included in the map.

  8. Finally, add the following line to close the <map> element:
    </map>
    

    The file should now look as follows:

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
     "C:\DITA-OT1.8.M2\dtd\technicalContent\dtd\map.dtd">
    
    <map title="World's Smallest DITA Project">
       <topicref href="wsdp_small_is_beautiful.xml" type="concept"/>
    </map>
    
  9. Select  File–>Save.

Now let’s generate some PDF!

Generate the World’s Smallest DITA Project to PDF


  1. In the directory where you installed the DITA OT (for example, C:\DITA-OT1.8.M2), double-click startcmd.bat (Windows) or run startcmd.sh (Linux, Mac).
  2. At the prompt, enter the following command:
    ant -f build_demo.xml

    The following message is displayed:

    [echo] Please enter the filename for the DITA map that you
    [echo] want to build including the directory path (if any).
    [echo] The filename must have the .ditamap extension.
    [echo] Note that relative paths that climb (..) are not supported yet.
    [echo] To build the sample, press return without entering anything.
    [input] The DITA map filename: [C:\DITA-OT1.6.M5\samples\hierarchy.ditamap]
  3. Type C:\Worlds_smallest_dita_project\worlds_smallest_dita_project.ditamap and press Enter.
    The following message is displayed:

     [echo]
     [echo] Please enter the name of the output directory or press return
     [echo] to accept the default.
     [input] The output directory (out): [out]
  4. Type C:\Worlds_smallest_dita_project\out and press Enter.
    This will create an out directory in the C:\Worlds_smallest_dita_project\ project directory.
    The following message is displayed:

     [echo] Please enter the type of output to generate.
     [echo] Options include: eclipse, tocjs, htmlhelp, javahelp, pdf, or web
     [echo] Use lowercase letters.
     [echo]
     [input] The output type: (eclipse, tocjs, htmlhelp, javahelp, pdf, [web], docbook)
  5. Type pdf and press Enter.
    The following message is displayed:

     [echo] Ready to build C:\Worlds_smallest_dita_project\worlds_smallest_dita_project.ditamap
     [echo] for PDF in C:\Worlds_smallest_dita_project\out
     [echo]
     [input] Continue? (Y, [y], N, n)
  6. Press Enter.
    The DITA OT converts the DITA map to PDF. After a few minutes, the following message is displayed:

    BUILD SUCCESSFUL
    Total time: 2 minutes 54 seconds

    Note: If you do not get this message, see Troubleshooting below

And… voilà! To look at your newly generated output, double-click the worlds_smallest_dita_project.pdf file in the following directory:
C:\Worlds_smallest_dita_project\out

What’s Next?


Now that you’ve created your first DITA project, you might try a few things:

  • Generate the file in html (hint: select the “web” option)
  • Add more text to your topic
  • Create another topic and add it to the map

The objective of this exercise was to take you through the whole process of creating a project in DITA and generating an output, using open-source tools. Now that you’re able to create a small project, you can build on this to learn DITA. The next step will be to plan your training, which will be the subject of the next post. Learning a new technology is like training for a race. I’m a runner, and I know that if I want to achieve a race goal (running a 10K, improving my race time), I need to plan my training week by week. If learning DITA on your own is your goal, then you also need a training plan.

Until the next post, be safe and have fun!

Troubleshooting


If you get an error message when generating your PDF file:

  1. Make sure that you can generate a PDF using the DITA OT sample project as described in the post on installing the tools. If you can generate the demo PDF but not the World’s Smallest DITA Project, then you know that the problem is with your code. Otherwise, the problem is with the DITA OT installation.
  2. Check that you are pointing to the right DTDs in the third line of your files.
  3. Make sure that the contents of your DITA files match the examples above.

If you still can’t figure out the issue, describe the problem in the comments section and I’ll try to help you figure it out.

Share this article:
Facebook Twitter Email Linkedin

8 Responses to “The World’s Smallest DITA Project Part 2: Let’s do it!”

  1. Jeanne says:

    Cool! It worked!!

    Thanks so much, Nathalie. This is fun.

  2. Craig Wright says:

    Thanks, I’m up and running. One thing I wondered – where did the formatting in the PDF come from?

    • Nathalie says:

      Ah, the PDF formatting, a very interesting question :) The DITA OT is responsible for the PDF formatting. If you’re interested in modifying it, I highly recommend the book DITA for Print by Leigh White. It will tell you everything you need to know about the DITA OT for PDF output; it’s very well written and very hands-on.

      Thanks for doing the procedures!

  3. Christina Eftekhar says:

    This is great! I hope to use a similar model to teach DITA to some new employees. This way it’s tool-agnostic and they get the idea of DITA without having to worry about a specific authoring tool yet.

  4. J McCarty-Bell says:

    Hi. Thanks so much for all the great help with this. It worked beautifully!

    I am trying to do the word to dita thing, but with no joy. The dita 4 publishers plugin gets part way through a document and then fails. Do you have any sources for help on this that you could point a guy toward? I am signed up for this months webinar on dita light, but that isn’t until the 14th.

    Thanks again,

    J McCarty-Bell

    • Nathalie says:

      Hello! Thanks for your feedback! I’m glad the instructions are helpful :)

      Unfortunately, I’ve never converted Word to DITA. I did a bit of research this morning, and quickly looked into the dita4publishers plugin. What kind of problems are you having? Does it tell you exactly where it crashes in your Word document? Is there something particular about your Word doc (e.g., an advanced Word feature) that might cause the issue?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>