This article addresses one task in the migration process that the conversion tools do not automate: Converting Eclipse TOC files to DITA map files. It does not discuss the reasons for converting HTML files to DITA format; other developerWorks articles and resources on the OASIS DITA Web site explain those advantages (see Resources). This article compares the elements of two XML-based navigation files and then uses sample master TOC and subordinate TOC files to illustrate the transformations to DITA. The article also provides instructions for using the XSLT stylesheet to convert your own Eclipse TOC files.

Fill the void in current tools

If you need to convert an Eclipse help plug-in to DITA, you can find tools for transforming your HTML files to XHMTL, and tools for converting the XHTML files to DITA. (See Resources for articles that describe such conversions.) Although most of the files in an Eclipse help plug-in are usually HTML, the Eclipse TOC file represents a major investment of design and development time. Several factors depend on the TOC file, including the information architecture, the contents of the search database, and the visibility of key topics. If you have invested heavily in your TOC files and the files work the way you want them to, you will not want to risk manually converting the files to DITA map files -- but good luck finding a conversion tool that handles that task. After not finding such a tool, I decided to write an XSLT stylesheet to convert my files.

Back to top

Compare the Eclipse TOC to the DITA map

Eclipse TOC files and DITA map files are both XML files that describe the navigation for a collection of topics. You'll find similarities and differences between the two types of files; for each valid element or attribute in an Eclipse TOC file, Table 1 identifies the corresponding element or attribute in a DITA map file. The attributes for each TOC element are listed after the element.

In the table, you can see that some elements are identical (such as <anchor>) or very similar. The similarities certainly made it easier for me to create an XSLT stylesheet to convert a TOC file to a DITA map file.

The remaining sections of this article describe the transformation of a set of sample TOC files to DITA map files. If you want to examine the sample files more closely as you read, download and extract the files in the root directory of the archive file x-ecldita-toc2dita.zip. (See Download for a link to the ZIP file.)

The download archive includes the sample TOC files, the corresponding DITA map files, and the XSLT stylesheet that's used to transform the TOC files. You can use a Web browser, an XML editor, or a text editor to view the TOC files. To view the DITA map files (extension .ditamap), you will need the IBM ID Workbench or the public DITA toolkit that is listed under Resources.

The plugins.zip file inside the x-ecldita-toc2dita.zip file contains the Eclipse TOC files from the root directory, packaged in two Eclipse plug-ins that you can install on an Eclipse help server.

Back to top

Transform master TOC files

In many cases, the navigation for an Eclipse-based help system consists of multiple TOC files that are integrated through a central master TOC file. The master file can contain any combination of the following types of elements:

• Topics (each specified by a <topic> element)
• Links to other TOC files that already exist (top-down integration)
• Anchors for extending the master TOC in the future (bottom-up integration)

Of course, the Eclipse help system does not require a master TOC file, but having one is definitely convenient when multiple content providers must work in parallel to develop a help system. Master TOC files are also essential when portions of the help system are installed at different times, such as a base product that can be upgraded by installing features. If it is necessary to integrate the feature help content with the base help system, then a master TOC file is essential.

In the download archive, the master TOC file is mastertoc.xml. Figure 1 shows the mastertoc.xml file beside a screenshot of how the integrated TOC files render in an Eclipse help browser. The master TOC file:

• Contributes the root collection labeled "Administration Central" and references a content file that is displayed when the user clicks the root collection
• Links to the subordinate collection (toca.xml)
• Provides an anchor for extending the master TOC in the future
• Contains a topic that provides notices to the user

When the master TOC is transformed to a DITA map file using the XSLT stylesheet (toc2dita_adv.xsl in the x-ecldita-toc2dita.zip file), the output file looks like Listing 1.

 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE map PUBLIC "-//IBM//DTD DITA Map//EN" "..\dtd\map.dtd">
<map title="Administration Central">
  <topicref navtitle="Administration Central" 
    href="admin_central.dita" print="no" toc="no"/> 
  <topicref navtitle="Console Basics" href="console_basics.dita"> 
     <navref mapref="toca.ditamap"/>
  </topicref> 
<anchor id="anchor_id"/>
<topicref navtitle="Notices" href="reference/notices.dita"/> 
</map> 

Of course, the sample master TOC is simplistic, but more complex master TOC files are just repetitions of the basic elements in the sample file. The XSLT stylesheet can handle complex TOC files, and it can process TOC files that reference file types other than HTML. The latest Eclipse technology supports rendering source files that are JavaServer Pages. So the XSLT stylesheet can handle the .jsp extension as well as .pdf, .gif, .htm, and .html.

Back to top

Transform subordinate TOC files

This section focuses on two examples of subordinate TOC files: files that the master TOC links to and files that the master TOC provides an anchor for. In the archive file, the subordinate TOC files are toca.xml and tocb.xml.

The toca.xml file is integrated with the master TOC through the <link> element which explicitly references toca.xml, assigns a label for the collection ("Console Basics"), and references a topic file that is displayed when the user clicks the collection label. Associating a topic file with the collection is not required; in such cases, the href attribute is not specified. Because the linking involves specific information about the subordinate TOC, that type of linking can only be done when the TOC file already exists or when the developer can trust that it will exist when the Eclipse plug-in for the master TOC file is installed. Figure 2 shows the contents of the toca.xml file on the right, and a view of how the content is displayed in the Eclipse help browser on the left.

In contrast to the toca.xml file, the tocb.xml file is integrated with the master TOC through the <anchor>. If the designer of the master TOC anticipates a future need to integrate another TOC file, the developer can add an anchor in the desired point of the master TOC. The future TOC file will reference that anchor. Multiple anchors are permitted, but only one TOC in the installation can reference a specific anchor. In tocb.xml, the link_to attribute of the <toc> element points to the anchor in the master TOC. Figure 3 shows the contents of the tocb.xml file on the right, and a view of how the content is displayed in the Eclipse help browser on the left.

Notice that the value of the link_to attribute is the relative URL of the master TOC file concatenated with the number sign (#) and the value of the id attribute of the <anchor> element. Because the tocb.xml file and the mastertoc.xml file are in separate Eclipse plug-ins, the relative URL contains the plug-in name for the master TOC. Figure 4 and Figure 5 show the directories for the two plug-ins: com.mycompany.plugin.doc (which contains mastertoc.xml and toca.xml) and com.mycompany.plugin.adv.doc (which contains tocb.xml).

When you transform tocb.xml to a DITA map file using the XSLT stylesheet in the x-ecldita-toc2dita.zip file, the output file looks like Listing 2. Notice that the link_to attribute in the TOC file transforms to an anchorref attribute in the map file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//IBM//DTD DITA Map//EN" "..\dtd\map.dtd"> 
<map title="Advanced" 
  anchorref="../com.mycompany.plugin.doc/mastertoc.ditamap#anchor_id"> 
  <topicref navtitle="Advanced topics" href="advanced.dita">
    <topicref navtitle="Adding resources" href="tasks/adding_res.dita"/>
    <topicref navtitle="Removing resources" href="tasks/removing_res.dita"/>
  </topicref>
</map>

Back to top

Transform your TOC files

You've seen the transformation of the samples file. Now, it's time to try transforming your own Eclipse TOC files. Here are the steps for setting up your system and running the transformation:

1. Download the archive x-ecldita-toc2dita.zip if you have not already done so. See Download near the end of this article.
2. Use PKZip, WinZip, or a similar tool to extract the files.
3. Create a folder to use as your transformation work area.
4. Copy the toc2dita_adv.xsl file from the x-ecldita-toc2dita.zip file to your work folder.
5. Copy your Eclipse TOC files to the same folder.
6. If you do not already have a copy of an XSLT stylesheet processor, obtain a copy. For example, to obtain the Apache Xalan processor, visit Apache.org (see Resources). The Xalan package is available as C++ code and as Java code. The Java package is easier for novices to use.
7. If you downloaded the Xalan-Java package, you will also need a Java Development Kit (JDK) because you must use the java command to run the processor class. If you have Rational Application Developer, WebSphere Application Server, or a similar Java-based application, you can use the JDK included with those applications. Otherwise, download a JDK from the Sun Developer's Site (see Resources).
8. Follow the instructions provided with the XSLT processor to transform each of your Eclipse TOC files. In the command, specify that the toc2dita_adv.xsl file is the XSLT stylesheet and that the output file extension is .ditamap. Here is an example of the command for using Xalan-Java to transform a TOC file.

 
java -classpath 
  c:\jdk142\lib\j2ee.jar;c:\xalan_dir\xalan.jar org.apache.xalan.xslt.Process 
  -IN toc.xml -XSL toc2dita_adv.xsl -OUT toc.ditamap

Back to top

Summary

When you migrate Eclipse help plug-ins to DITA format, you do not have to manually convert Eclipse TOC files to DITA map files. XSLT enables an easy, automated method to make this conversion, which reduces the risk of error and speeds the migration process. The download for this article provides an XSLT stylesheet for such transformations.

This article only addressed converting TOC files to DITA map files. In some cases, DITA maplists would be appropriate. In some cases, newer features of the OASIS DITA 1.0 specification (the "ditamap" format option) would be appropriate.

Back to top

Download

Information about download methods

Resources

• Learn more about DITA in these developerWorks articles:
  • "Introduction to DITA" (October 2003)
  • "Specializing topic types in DITA" (October 2003)
  • The DITA FAQ (November 2004)
  • "Specializing domains in DITA" (October 2003)
  • "Why use DITA to produce HTML deliverables?" (October 2003)
  • "Design patterns for information architecture with DITA map domains" (September 2004)
  • The two-part series "Migrating HTML to DITA" -- Part 1, "Simple steps to move from HTML to DITA " (January 2005) and Part 2, "Extend the migration for more robust results" (February 2005).
  
  
  
• Get the public DITA toolkit which contains the DITA Document Type Definitions (DTDs), stylesheets for transforming XHTML files to DITA, and sample files. You can also find these items at the new DITA Open Toolkit Project Home page.
  
  
• Find additional information on DITA at the OASIS Cover Pages.
  
  
• Check out these resources on Eclipse:
  • "Documenting your project using the Eclipse help system" (developerWorks, January 2004) describes the basic steps for developing an Eclipse help plug-in.
  • For detailed information and development resources, visit the Platform Help System section of the Eclipse Web site.
  
  
  
• Need an XSLT stylesheet processor? Try Xalan, available at Apache.org in both C++ and Java-language versions.
  
  
• If you plan to use the Xalan-Java package, you will also need a Java Development Kit (JDK). If you have Rational Application Developer, WebSphere Application Server, or a similar Java-based application, you can use the JDK included with those applications. Otherwise, download a JDK from the Sun Developer's Site.
  
  
• For more information about XSLT, see the following resources:
  • "What kind of language is XSLT?" (developerWorks, February 2001) provides an overview of XSLT with stylesheet examples.
  • Visit the World Wide Web Consortium (W3C) Web site for the XSLT specification and information about tools.
  
  
  
• Find hundreds more XML resources on the developerWorks XML zone.
  
  
• Learn how you can become an IBM Certified Developer in XML and related technologies.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Fill the void in current tools
• Compare the Eclipse TOC to the DITA map
• Transform master TOC files
• Transform subordinate TOC files
• Transform your TOC files
• Summary
• Download
• Resources
• About the author
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, pureXML, Zend Core PHP, and Java you can develope advanced Web 2.0 applications quickly that matter.

---

• Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data.
• Article: See how DB2 pureXML schema capabilities can evolve schemas without making any changes to your applications.
• Tutorial: This tutorial shows you how to use DB2's pureXML to expose the native XML capabilities of DB2.
• Buy: DB2 9 for Linux, UNIX and Windows

My developerWorks community

Dig deeper into XML on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers