Convert eclipse navigation file to Dita navigation file

This article describes how to complete a task that the conversion tool cannot automate during a migration: convert the Eclipse TOC file to a DITA mapping file. There is no discussion of the reason to convert HTML files to DITA format, and other developerWorks articles and references on the OASIS DITA Web site will explain their advantages. This article compares the elements in two xml-based navigation files and then demonstrates the conversion to DITA using the sample main TOC file and the secondary TOC file. It also provides guidance for converting Eclipse TOC files using XSLT style sheets.

Fill in the blanks of the current tool

If you need to convert the Eclipse help plug-in to Dita, you can find tools to convert HTML files to XHTML and to convert XHTML to Dita. Although most of the files in the Eclipse Help plug-in are usually HTML, the eclipse TOC file still costs a lot of design and development time. There are several elements based on the TOC file: Information structure, search database directory, and visibility of key topics. If you've put a lot of effort into the TOC file and the files work as you wish, you will never risk using manual methods to convert the files to a DITA mapping file-unless you're lucky enough to find the transformation tool that handles the task. After I had not found such a tool, I decided to write my own XSLT style sheet to transform the file.

Compare Eclipse TOC with DITA mapping

Both the Eclipse TOC file and the DITA mapping file are XML files that are used to describe navigation for a set of topics. You will find similarities and differences between the two types of files. For each legitimate element or attribute in the Eclipse TOC file, table 1 lists the corresponding elements in the DITA mapping file. The attributes for each TOC element are listed behind the element.

Table 1. One-by-one comparison of Eclipse TOC elements with DITA mapping elements

TOC element or attribute	Mapping elements or attributes	Comments
<toc>	<map>	They are the root element of the document
Link_to	Anchorref	These properties point to the insertion point (TOC or DITA mapping file) in another topic hierarchy. The topic hierarchy is integrated with another topic hierarchy at the insertion point. This is also known as bottom-up integration.
Label	Title	The Label property is required for the <toc> element.
Topic	<topicref>	The first <topicref> element in the DITA map is used to hold the topic attribute of the <toc> element in the Eclipse TOC file. The value of the topic property is used to set the value of the HREF property for <topicref>. The print and TOC properties of the <topicref> element are set to "no".
<topic>	<topicref>	If the <topic> element does not have an HREF attribute, you can convert the <topic> element to a <topichead> element.
Label	Navtitle	The Label property is required for the <topic> element.
Href	Href	The href attribute value of the <topic> element is used to set the value of the href attribute of the <topicref> element.
<anchor>	<anchor>	These elements define the insertion point where other topic hierarchies can connect (<toc> link_to attributes) or references (<map> element anchorref properties).
Id	Id	The id attribute is required for the <anchor> element.
<link>	<navref>	These elements point to another topic hierarchy. Another topic hierarchy is consolidated at this insertion point with this topic hierarchy. This is also referred to as Top-down integration.
Toc	Mapref	The TOC property is required for the <topic> element.

From this table, you can see that some elements are the same (such as <anchor>) or very similar. These similarities make it easy for me to create an XSLT style sheet to convert a TOC file into a DITA mapping file.

The remainder of this article describes a transformation of a set of sample TOC files to a DITA mapping file. If you want to examine these sample files more carefully while you are reading, download and extract the files from the root directory of the X-ecldita-toc2dita.zip file.

The downloaded profile includes the TOC file, the corresponding DITA mapping file, and the XSLT style sheet (used to transform the TOC file). You can view a TOC file by using a Web browser, an XML editor, or a text editor. To view the DITA mapping file (. ditamap extension), you need to use the IBM ID Workbench.

The Plugins.zip file in the X-ecldita-toc2dita.zip file contains eclipse TOC files from the root directory, which are packaged into two eclipse Plug-ins that can be installed on the Eclipse Help server 。