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!
 

Share this article:
Facebook Twitter Email Linkedin

6 Responses to “Creating Eclipse Context-Sensitive Help (CSH) from DITA”

  1. Jeanne says:

    Nathalie, brilliant post! You make it sound so simple.

    Question: How are the IDs determined for the UI areas? Does the developer or the writer come up with them?

    Thanks again for the clear explanation and the resulting screenshots. Looks great.

  2. Nathalie says:

    It’s actually a team effort. There had been an attempt at CSH in a previous version of the DITA CMS, so some IDs were already there, but I came up with the new ones. We’ve determined that the writer should be responsible for these IDs, so I now maintain the list.

    Thanks for your feedback!

    • Jeanne says:

      Great. I’d prefer to have control over the IDs as well.

      Is there custom coding that must be done by the developer on the Eclipse side for this to work?

      • Nathalie says:

        No, that’s the beauty of this solution, the developer can use the existing Eclipse help API as is. He only needs to set the ID for the UI element in the code for this element and that’s it! :)

  3. Kirthika says:

    Hi Nathalie,

    I’m a Technical Writer, I had an opportunity to work in XML based tool.

    Recently, I got job and I need to work in X-metal. I have basic knowledge of the tool but I do not know how to create tags and editing existing tags? How can I edit the margin of the page setup?

    And also I want to know about managing image in X-metal. Because sometimes, the image appears without color like for example in the warning image It shows the yellow color inside the tool but not in Final PDF. What would be the problem?

    I do not know coding and all. Could you please guide me?

    Thanks in advance

    • Nathalie says:

      First of all, congratulations on your new job! :)

      Unfortunately, I haven’t worked with XMetaL, so I do not know this tool enough to help you. I would recommend looking at the XMetaL documentation or maybe posting on their forum, if they have one.

      Good luck!

Leave a Reply

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