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

Creating Eclipse Context-Sensitive Help (CSH) from DITA

At IXIASOFT, our CCMS runs on Eclipse, so our user and admin guides are provided as Eclipse documentation (generated using the DITA-OT Eclipse plugin), in addition to HTML and PDF files available on our website. In our latest release, we decided to add context-sensitive help (CSH) to the CCMS so that our users could get help as they were doing their tasks.

Sounds simple, right? Not exactly.

As Dan Elfanbaum mentioned in his article, it’s almost impossible to find information on how to integrate CSH from DITA into Eclipse. Yan Periard, our Chief Artisan, and I sat down to determine how we would approach this and we came up with our own method. (Okay, Yan did most of the technical research and coding, but I encouraged him every step of the way :). I’m sharing our solution here in the hope that it might be useful to others.

Our requirements were simple:

  • No new documentation; we wanted to reuse our current DITA topics to generate the CSH, as we’re doing for the PDF, HTML, and Eclipse outputs
  • The CSH should be unobstrusive
  • The CSH should link to the complete Eclipse documentation for more information

To display CSH, Eclipse expects a context file that looks as follows:

<contexts>
   <context id="panic_button" title="Panic Button Title">
      <description>This is the panic button.</description>
      <topic href="reference/panic_button.htm" label="Panic Button Reference"/>
   </context>
   ...
</contexts>

Eclipse requires the following information in the context file:

  • id: ID that identifies the element of the UI. This ID must be declared in the CCMS Eclipse code.
  • title: Title of the CSH window displayed when users click F1 while hovering over the UI element.
  • description: Short description of the UI element.
  • topic: One or more topics that will be listed in the CSH window to provide more information to the user. The href must link to one of the topics in the documentation plugin.

So our challenge was: How do we go from DITA source code to the context file required by Eclipse? We first thought about creating a specialization that would map exactly to the context file, but we try to stay away from them for usability. We wanted our solution to be as generic as possible.

So we came up with the following approach:

  1. Create a standard DITA context map that includes the information required by the Eclipse context file.
  2. Transform the context map into a context file recognized by Eclipse.

 

1. Create the context map


Mapping the information required by Eclipse into a DITA map was fairly straightforward, but we had one complication. Our product can be used with oXygen and XMetaL, and the user guide is XML-editor specific, so it’s packaged in two different Eclipse plugins:
– DITA CMS User Guide for oXygen (com.ixiasoft.eclipse.help.userguide.oxygen)
– DITA CMS User Guide for XMetaL (com.ixiasoft.eclipse.help.userguide.xmetal)

Most customers use one of these XML editors, but some use both. This meant that when clicking F1 on an area of the UI, some customers had to be shown the oXygen version of the documentation, some customers the XMetaL version, and other customers needed both versions. We therefore had to find a way to conditionalize the <topic href> required by Eclipse. After some discussion, we ended up with the following map:
 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd">
<map id ="lar1410796284657" xml:lang ="en-us">
   <title> DITA CMS User Guide Context Map</title >
   <topicmeta id="help.plugins.root" >
      <resourceid appname ="com.ixiasoft.eclipse.help.userguide.oxygen" id="Oxygen"/>
      <resourceid appname ="com.ixiasoft.eclipse.help.userguide.xmetal" id="XMetal"/>
   </topicmeta >
   <topicgroup id ="referable_content_view">
      <topicmeta>
         <navtitle> About the Referable-Content view</ navtitle>
         <shortdesc> The Referable-Content view lets you search for reusable components 
                     and insert them into documents.</ shortdesc>           
      </topicmeta>
      <topicref href ="lar1396892881040.xml"/>
      <topicref href ="lar1399915347457.xml"/>
      <topicref href ="lar1399921717895.xml"/>
      <topicref href ="lar1397657467945.xml" product="XMetal"/>
      <topicref href ="lar1397657445991.xml" product="Oxygen"/>
   </topicgroup>
</map>

We mapped the information required by Eclipse to DITA elements or attributes as follows:

  • The map-level <topicmeta> defines the Eclipse documentation plugins to which this CSH applies:
    • The id defines the location of the help plugin to Eclipse.
    • The resourceid defines the name of the Eclipse plugin (in the appname attribute) as well as an id to determine whether this is the oXygen or XMetaL plugin.
  • The <topicgroup> contains the information to create the <context> element required by Eclipse:
    • The id defines the id of the UI object. This must match the id put in by developers in the CCMS code.
    • The <topicmeta> then provides the title and description of the window for the CSH. I typed in the text directly, but I could have pulled the <shortdesc> from my original topics using a conref (planned for Phase 2 of the project).
    • Each <topicref> then defines the topic to display for this UI object. For example, for the Referable-Content view above, I determined that five topics from the user guide were interesting enough to be displayed. The first three are common to both XMetaL and oXygen but the last ones are editor-specific, so we used the product condition to identify them.

The map above shows only one topicgroup, for simplicity, but obviously I created one topicgroup for each area of the UI that would benefit from additional information.

 

2. Transform the context map into the Eclipse context file


For this, we created our own transformation, which basically takes the DITA context map and transforms it into an Eclipse context file (contexts.xml) using an XSLT transformation. We implemented this transformation using the Output Generator, which is the IXIASOFT DITA CMS module that outputs DITA source into the required output type, but you could easily reproduce this as a DITA-OT script. It uses Ant code, as follows:

<target name="dita2eclipsecontexthelpwrapper">
   <xslt processor="trax"
         in="input_map.ditamap"
         out="contexts.xml"
         style="ixiasoft_eclipse_csh_transfo.xsl">
         <xmlcatalog id="ixia.dita.catalog"/>
   </xslt>
</target>

(For your convenience, you can find the XSLT file here; right-click the link to download the file).

The output contexts.xml looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<contexts>
<context id="referable_content_view" title="About the Referable-Content view">
      <description>The Referable-Content view lets you search for reusable components and insert them into documents.</description>
      <topic href="PLUGINS_ROOT/com.ixiasoft.eclipse.help.userguide.oxygen/lar1396892881040.html"
             label="Working with the Referable-Content view">
         <enablement>
            <with variable="platform">
               <test property="org.eclipse.core.runtime.isBundleInstalled"
                     args="com.ixiasoft.eclipse.help.userguide.oxygen"/>
            </with>
         </enablement>
      </topic>
      .....
   </context>

Once the contexts.xml file is generated, it’s packaged with the two DITA CMS documentation plugins for XMetaL and for oXygen. And voilà! You have CSH that looks something like this when users press F1:

Sample CSH

Sample CSH

The help window is opened as an Eclipse view (shown below), so it’s unobtrusive and gets updated as the user moves around the UI.

Unobstrusive help
 
This was a fairly long post, but I’m hoping it will help other writers/developers trying to create Eclipse CSH from DITA. As usual, comments and questions are welcome!
 


DITA 1.3: Coming soon to an editor near you

The OASIS committee has been working hard at preparing the new release of the DITA specification, DITA 1.3, which is currently planned for Q1 of 2015. In addition to bug fixes and miscellaneous quality improvements, DITA 1.3 will introduce some very interesting features, including:

  • Better support for context-sensitive help
  • A new topic type for troubleshooting
  • Conditional processing enhancements
  • Enhancements to the DITA 1.2 key and keyref feature (scoped keys)
  • New domains for MathML, SVG, and release management
  • Improvements to the Learning and Training domain

My original plan for today was to cover all the new features, but it made for a very long blog post. So instead I’ll go over each important feature in separate posts over the next few weeks. If you’re impatient and want to know the details of the DITA 1.3 specification right now, see the links at the bottom of this post.

Note: Since DITA 1.3 is not released yet, the specification may change and the information and samples in this post may need to be revised.

Let’s start with context-sensitive help.

Better support of context-sensitive help

The current DITA specification is very limited in terms of support provided for context-sensitive help (CSH). DITA 1.3 plans to address the following two limitations:

  • Inability to manage multiple CSH callback IDs from the same DITA source
  • Inability to specify target runtime display from the DITA source

Managing multiple CSH callback IDs from the same DITA source

When generating CSH from DITA, the <resourceid> element can be used to specify the callback ID, which is the hook used to link the DITA topic to the appropriate user interface area. For example, we used the <resourceid> element as follows for the Web Author help:

<prolog>
 <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/>
</prolog>

The problem with DITA 1.2 is that the <resourceid> metadata is limited in the information it can contain to differentiate between multiple target outputs. For example, consider a topic that is used in three different target outputs: Online help, embedded user assistance, and mobile help. If each target application uses its own callback ID scheme, then multiple different context IDs must be specified for the same topic. Since this information cannot be specified in the DITA 1.2 <resourceid> metadata, the mapping between the DITA source topic and the callback IDs must be maintained outside of the DITA files.

To solve this issue, DITA 1.3 adds three new metadata attributes to <resourceid>:

  • appid: Identifies a referenced topic to an external application
  • ux-context-string: Specifies a callback context ID for that topic
  • ux-source-priority: Since the resourceid metadata can be set at the map level or the topic level, this attribute specifies how to resolve conflicts between callbacks defined in a map and in a topic; valid values are map-takes-priority and topic-takes-priority. So if the resourceid information provided in the topic is different from the resourceid provided for that topic in the map, this attribute specifies which resourceid to use.

For example, the following code configures callbacks for two target outputs for the create_image topic: One for the Web Author application and one for the Eclipse Client.

<map title=”DITA CMS Help”>
  <topicref href=”create_image.dita” type=”task”>
    <topicmeta>
      <resourceid
        appname=”cms.webauthor”
        appid=”create_image”
        ux-content-string=”com.ixiasoft.webauthor.help.create_image”
        ux-source-priority=”map-takes-priority”/>
      <resourceid
        appname=”cms.eclipseclient”
        appid=”create_image”
        ux-content-string=”com.ixiasoft.eclipseclient.help.create_image”
        ux-source-priority=”map-takes-priority”/>
    </topicmeta>
  </topicref>
</map>

I’m assuming that the appid attribute in DITA 1.3 is replacing the id attribute in DITA 1.2, since I don’t see why we would need both.

Specifying target runtime display from the DITA source

To provide the details of the target display, DITA 1.3 also adds a new element, <ux-window>, and a new attribute for <resourceid>:

  • <ux-window>:  This element lets you configure a target display profile and include information such as the size of the window, some of its features, etc. For example, the following <ux-window> element configures the display for a mobile environment:
    <topicmeta> 
      <ux-window id=”task_window” name=”mobile_ios” top=”10″ left=”20″ 
       height=”400″ width=”500″ 
       features=”status=yes,toolbar=no,menubar=no,location=no” 
       relative=”true” full-screen=”no”/> 
    </topicmeta>
    
  • You can then specify this profile in the ux-windowref attribute of the resourceid, as shown below:
    <resourceid 
     appname=”cms.webauthor” 
     appid=”cms.webauthor.mobile” 
     ux-content-string=”com.ixiasoft.webauthor.help.create_image″ 
     ux-source-priority=”map-takes-priority” 
     ux-windowref=”mobile_ios”/>
    

I’m not sure yet about this new improvement. One of the strengths of DITA has always been to separate the source content from how it will look in the output. I see this kind of specification as more appropriate in a transformation scenario. But maybe it’s a requirement for mobile environments, and since I haven’t had to produce mobile help yet, I’m not allowed to complain. :)

In the next post, I’ll cover the new topic type for troubleshooting. Should be interesting!


For more information about DITA 1.3:


DITA and user assistance: Real-world implementation

In a post that I published last year, I said that I would document how we implemented Ray Gallon’s double-embeddedness theory for a project we were developing. Here I am, a year later, with the details of this implementation. Better late than never, right? :)

The theory


Let’s start by summarizing Ray’s theory.

The concepts: Cognition and context

There are two main concepts in this theory:

  • Users learn best when the information they need to perform a task is available as they are performing the task.
  • Users learn best when they understand why they are performing a task. They need to know quickly if they need to perform a task. They need concepts as they are performing their tasks.

The solution: Double embeddedness

The solution is what Ray calls “double embeddedness”:

  • Embed the user assistance directly in the user interface.
  • Embed simple concepts directly into the user assistance.

…with progressive disclosure:

  • Initially, show users only a few of the most important options.
  • Offer a larger set of specialized options upon request, and disclose these secondary features only if a user asks for them, meaning that most users can proceed with their tasks without worrying about this added complexity.

In summary, we want user assistance that:

  • Gives users all the information they need and only the information they need
  • Delivers that information when they need it
  • Includes a sentence or two of conceptual information in context
  • Is embedded in the UI in such a way that:
    • The user can find it immediately, without excessive searching
    • If the user doesn’t need the help, it stays out of the way

Real-life implementation: Web Author user assistance


I sat down with the developers at IXIASOFT to discuss how we could implement this theory in our new product, called Web Author. The Web Author is a web editor that allows casual contributors and reviewers to edit and review DITA topics from an Internet browser. Because users would not be familiar with DITA and would not use this tool every day, it was a perfect candidate for the type of user assistance that Ray talked about.

We started by defining three levels of help.

Level 1: Tooltips

When users hover over an element of the UI, a pop-up is displayed with a short overview of the function. The tooltip provides some conceptual information to put users in context as they are performing the task.

The following diagram shows a sample tooltip. When a user logs in, the Web Author lists the documents that are assigned to the user. The number of documents assigned is displayed in the Number of assignments area. When users hover over this area (the purple square with a number in it), the following tooltip is displayed:

Level 1: Tool tip

Level 1: Tool tip

The tooltip contains a More… link so if users need more information about the area, they click the link and level 2 help is displayed.

Level 2: Help area details

Level 2 help provides more detailed information about the area as well as links to what you can do in this area (i.e., the actual procedures). For example, if a user clicks More in the Number of assignments tooltip, the following window is displayed:

Level 2: Help details

Level 2; Help details

The level 2 help is not displayed in a pop-up window, it’s embedded in the user interface, in the lower left corner of the main window, as shown above.

Another requirement of Ray’s theory is that help should be unobtrusive and be out of the way if users don’t need it. For this, we added the hide tips/show tips toggle button on top of the help details window (shown above). When users are familiar enough with the user interface and no longer want the help, they can simply disable it by clicking hide tips. Should they need to see the help again later on, they simply click the show tips button.

If a user still needs more information, clicking one of the related links will open the level 3 help.

Level 3: HTML Help

This is a standard HTML help system available in another tab of the browser. When users click the links in the help details area, they are taken to the corresponding procedure in the online help, shown below:

Level 3: Help system

Level 3: Help system

DITA implementation


To implement the user assistance, we decided to use the DITA <resourceid> element and outputclass attribute.

To link the DITA topic to the appropriate user interface area, we use the <resourceid> element in the <prolog>. For example, to specify the topic that applies to the Number of assignments area, we added the following code to the topic:

 <prolog>
   <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/>
 </prolog>

The appname specifies the product name (in this case, the Web Author) and the resourceid specifies the resource id of the area as specified in the Java code. This ensures that when a user hovers over an area, the Web Author knows from which topic to pull the documentation.

Using the <resourceid> element for context-sensitive help is a pretty standard approach. What’s different about our implementation is that we decided to use the outputclass attribute to identify what to display at each level of help.

We defined three values for outputclass:

  • outputclass="help_tooltip": Defines level 1 help
  • outputclass="help_context": Defines level 2 help
  • outputclass="help_related_information": Defines the related links that will open the HTML help

For example, the following code shows the DITA file for the Number of assignments topic:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//IXIA//DTD IXIA DITA Composite//EN" "../../system/dtd/ixia/IxiaDitabase.dtd">
<concept id="per1389986405854" xml:lang="en-us">
	<title>Number of assignments area</title>
    <shortdesc outputclass="help_tooltip"><ph id="number">Displays the number of documents assigned to you in the
        role selected.</ph> </shortdesc>
    <prolog>
        <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/>
    </prolog>
   <conbody>
       <section outputclass="help_context">
           <p>When you select a role in the <uicontrol>Roles</uicontrol> drop-down list, all the
                documents assigned to you and active for that role are displayed in the Assignments
                pane, and the number of documents is updated in the <uicontrol>Number of
                    assignments</uicontrol> area.</p>
            <p>To refresh the list and the number of active documents, click the
                    <uicontrol>Refresh</uicontrol> icon in the <wintitle>Number of
                    assignments</wintitle> area.</p>
       </section>
   </conbody>
    <related-links outputclass="help_related_information">     
        <link href="per1389986405575.xml#per1389986405575" outputclass="help_related_information_link"/>
        <link href="per1389986404838.xml#per1389986404838" outputclass="help_related_information_link"/>
        <link href="per1389986405139.xml#per1389986405139" outputclass="help_related_information_link"/>
    </related-links>
</concept>

When a user hovers over the Number of assignments area, the user assistance looks for the element with the outputclass="help_tooltip". This is usually the <shortdesc> element. If a user clicks the More… link, the user assistance then looks for the element with the outputclass="help_context". In the example above, the attribute is set on the <section> element, so this whole element is included in the help details. The related links specified with the outputclass="help_related_information" are displayed at the bottom of the help details. If a user clicks one of these links, then the user assistance opens up the complete HTML help.

This is shown in the following diagram (you might want to click the diagram to enlarge it and see the details):

Summary of user assistance

Summary of user assistance

One of the advantages of using the outputclass is that it’s valid on any DITA element, so it’s very flexible; the user assistance only needs to look for the defined outputclass, no matter the type of topic. We can use any element in any type of topic to produce the user assistance.

Another advantage of using the outputclass attribute is that the same source content can be used for the user assistance, the HTML online help, as well as a PDF User Guide that was requested by our customers. But this will be the subject of another post, since this one is getting long enough already.

Summary
As you can see from this approach, a lot of magic happens behind the scenes (i.e., in the software) to enable this user assistance. I am lucky enough to work with developers who think that documentation and user assistance are very important, so they decided to treat the user assistance as a feature of the product. They developed a custom XSLT transformation scenario that generates an .hlp file with the user assistance. They also added code to the Web Author that extracts the right level of help according to user actions.

So yes, this method requires custom code from developers, but I think it’s a great example of how DITA can be used to create context-sensitive help.

Again, special thanks to Ray Gallon for his research and very inspiring webinar.


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.


The World’s Smallest DITA Project Part 1: Installing the tools

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

Before you can start having fun with DITA, you need to install the following tools:

  • A DITA editor
  • The DITA Open Toolkit

You use a DITA editor to write your topics, create your maps, and add your topics to maps. To generate your DITA content into the output format of your choice (PDF, .chm, HTML, etc.), you use the DITA Open Toolkit publishing engine, as shown in the following diagram:

DITA editor


An ideal DITA editor has the following features:

  • It includes a visual interface that lets you enter content without having to worry about tags. While it’s very useful to understand the DITA tags and be able to work with them, you don’t want to worry about the mechanics when you are writing your content.
  • It also includes a text interface that lets you work in the DITA code. This is very useful when you perform more complex operations such as applying conditions, adding cross-references, setting variables, etc. I work in the visual interface about 80% of the time and in the text interface 20% of the time.
  • It checks the syntax of your DITA code. Even when you’re working in a visual interface that does most of the job for you, you may still make mistakes. A good DITA editor will check your syntax as you type and will let you know when you make mistakes.

I’ve spent a few hours searching for a free XML editor that provides these features, but none seems available (and if I’m wrong, please, please let me know!). Many products provide a 30-day free trial, such as oXygen (which I use and love), and I’ll discuss this option when planning your DITA training.

For the World’s Smallest DITA Project, we will use Notepad++. It’s free, easy to use, and will work fine for what we want to do. Yes, when using Notepad++ you will be working with the tags, but as Sarah O’Keefe from Scriptorium said: “If you don’t understand the underlying DITA structure, you’re just going to continue to create badly structured information that is technically valid.”

Downloading and installing Notepad++

Notepad++ is a very common editor, and you may already have it installed on your computer.

If you don’t, follow these instructions:

  1. Go to the following URL:
    http://notepad-plus-plus.org/download/v6.5.2.html.
  2. Click the DOWNLOAD button.
  3. When the file is downloaded, run the installer.
  4. Follow the instructions, using the default selections.
    Note: If you get errors indicating that a file is moved to the “disable” directory, simply ignore them and click OK.
  5. When the installation is completed, click Finish.

DITA Open Toolkit


The DITA Open Toolkit (also called the DITA-OT) is an open source publishing tool that converts DITA content into various output formats such as PDF, XHTML, Eclipse Help, HTML Help, etc. To generate the output of a DITA map or topic, you run a command-line DITA-OT script that takes the map or topic as input and generates the content.

To download and install the DITA Open Toolkit:

  1. Go to the DITA Open Toolkit download website:
    http://dita-ot.github.io/download.html
  2. Click the button for your operating system.
    The file is downloaded to your system. The Open Toolkit is packaged as a .zip (Windows) or .tar.gz (Unix, Mac) file.
  3. Extract the file to the C:\ directory (Windows).
    The DITA OT is now installed in the C:\DITA-OT1.8.M2 directory.

The next step is to run the demo project provided with the DITA-OT to test your installation. To build the demo project, you run a script that asks for the DITA map that you want to build, the directory where you will store the output, and the type of output you want to create. For this test, we’ll accept the default answers to all questions.

  1. In the  C:\DITA-OT1.8.M2 directory, double-click startcmd.bat (Windows) or run startcmd.sh (Linux, Mac).
  2. At the prompt, enter the following command to build the demo project:
    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]

    Note: If you get the following error message instead:

    "java.exe"' is not recognized as an internal or external command...

    You need to update your system PATH variable with the location of your Java bin directory (for example, C:\Program Files\Java\jre7\) before you can try again. See these Java instructions for more information.

  3. Press Enter to use the default DITA map filename.
    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. Press Enter to use the default output 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. Press Enter to generate the map to XHTML.
    The following message is displayed:

     [echo] Ready to build C:\DITA-OT1.6.M5\samples\hierarchy.ditamap
     [echo] for web in out
     [echo]
     [input] Continue? (Y, [y], N, n)
  6. Press Enter.
    The DITA OT converts the DITA map to XHTML. 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 the DITA OT user documentation at the following location:
    C:\DITA-OT1.8.M2\doc\userguide.pdf

    If you can’t make this work by following the documentation, please post your error in the comments section below and I’ll try to help you fix the issue.

  7. To look at your newly generated output, double-click the index.html file in the following directory:
    C:\DITA-OT1.8.M2\out

If you want, you can run this procedure again, this time choosing a different output type.

What’s Next?


You are now ready to write your first DITA document! This will be the subject of the next post.  I will be off snowshoeing during the holidays and will come back with part 2 of the World’s Smallest DITA Project in 2014.

Until then…Happy Holidays, be safe, and be happy. :)


For the curious:

  • To lean more about the features that you need in a DITA editor, read this article from the April 2008 STC intercom issue. It’s five years old, so the list of tools is out of date, but the article still provides very useful information.
  • The DITA Writer has compiled a list of DITA optimized editors, which are XML editors best suited for producing DITA content.


« Previous Entries