Migrating Help Contributions

Migrating Online Help Contributions from version 1.0 to version 2.0.

INTRODUCTION
MAPPING BETWEEN 1.0 and 2.0 CONTRIBUTION MECHANISMS
EXAMPLE
ADVANCED CASES
     Handling topic having different children in each of information views
     Handling standalone information sets
     Handling single topic inserted from the middle of a topic file
     Internationalization

INTRODUCTION

The 2.0 help system concepts are described in Online Help Changes document. This document is designated to help converting existing help contributions created for version 1.0 of help system to form appropriate for use with the new help system. It contains comparison of contributions in the old and new help system with suggested conversion methods. Included is simple example of converting documentation specified in 1.0 syntax to the 2.0 syntax.

MAPPING BETWEEN 1.0 and 2.0 CONTRIBUTION MECHANISM

First, it is worth mentioning that that documentation content - the HTML files do not change between the help system versions 1.0 and 2.0. All documentation written and placed in a zip file does not have to be edited. The changes affect files describing documentation structure: information sets, views, topics, insert actions, and their file's descriptor in plugin.xml.

The largest part of the 1.0 help structure - the topics files, with tree of "topic" elements, has not changed significantly. They can be reused in 2.0 syntax with minimal changes. Both information set files and action files have been eliminated. The information contained in these files - how to integrate topics has its place inside the TOC files.

The mechanism used for specifying integration of topics existing in separate TOC available to help system is called linking. Linking allows for associating a root of one tree with an arbitrary point in another tree, to create bigger tree. This linking can be specified arbitrarily in any of the two TOCs involved in the operation. This freedom allows for any of the two approaches for creating table of contents for a product. In top-down approach a TOC links the root of another TOC, in bottom-up a TOC root links to an anchor point defined in another TOC.

The following table identifies significant 1.0 help system artifacts and their translation to 2.0 help system concepts.

1.0 2.0

extension point "org.eclipse.help.contributions" extension point "org.eclipse.help.toc"

three kinds of XML files describing information sets and views, topics, and actions one type of XML files describing tables of contents

topic XML file TOC XML file

topic file description in plugin.xml
<extension point="org.eclipse.help.contributions">
     <topics name="topics.xml" />
</extension> TOC file description in plugin.xml
<extension point="org.eclipse.help.toc">
     <toc file="topics.xml" />
</extension>

<topic> element in topics file
<topic id="topic1ID" label="Topic1" href="topic1.html" /> <topic> element in TOC file
<topic label="Topic1" href="topic1.html" />
The "id" attribute is no longer used. A topic does not need to be referred to from anywhere else. If topic files are converted to TOC files and "id" attributes are left, help system will ignore them and not generate errors.

<topics> element in topics file
<topics id="topics3ID"> <toc> element in TOC file
<toc label="Topics3X">
The "id" attribute is no longer required. The TOC is identified by the URL of the file that defines it.
e.g. "topics.xml" or "../myPluginID/topics.xml" if referred from another plugin.
Each TOC needs a label that describes content of the TOC, and may be visible to the end user if the TOC is included in the documentation library as top level TOC.

information set XML file TOC XML file designated as primary
Any TOC can play a role of the "old" information set by being designated as primary. The primary TOCs can be displayed as top level TOC to the user.

information set file description in plugin.xml
<extension point="org.eclipse.help.contributions">
     <infoset name="infoset.xml" />
</extension> primary TOC file description in plugin.xml
<extension point="org.eclipse.help.toc">
     <toc file="topics.xml" primary="true" />
</extension>

information set
<infoset id="myInfoSetID" label="MyInfoSetLabel" >

primary TOC
<toc label="MyInfoSetLabel">
The "id" attribute is no longer required. The TOC is identified by the URL of the file that defines it.
When TOC is displayed to the user its label plays the same role as the information set label in version 1.0.

standalone information set primary TOC

information view
<infoview id="myInfoViewID" label="MyInfoViewLabel" /> primary TOC
<toc label="MyInfoViewLabel">
All primary TOCs appear in the documentation library. They can be linked to other TOCs, and then do not show as top level TOC, but are available as part of another TOC.
The "id" attribute is no longer required. The TOC is identified by the URL of the file it is defined in.
When TOC is displayed to the user its label plays the same role as the information set label in version 1.0.

actions XML file -
Linking is specified directly in the involved TOC files.

<insert> element in actions file
<insert from="topicsID" to="topicID" /> <link> element in one of the linked TOC files
<link toc="topics.xml" />
OR
<anchor> element in one TOC files and "link_to" attribute in<toc> element in the second TOC file
<anchor id="topicsID"/>
<toc label="Topics Label" link_to="topics.xml#topicsID" />
"as" attribute is not needed, as location of <link> or <anchor> element uniquely define point of integration. Multiple <anchor> elements can be used to achieve desired order of TOCs linked such they become children of the same topic.

<insert from="anotherPluginID.topicsID" to="topicID" />
inserting topics from another plugin to topic in this plugin <link toc="../anotherPluginID/topics.xml />
"link" is placed in TOC file as a child of the topic previously identified by the "to" attribute.

<insert from="topicsID" to="anotherPluginID.topicID" />
inserting topics from this plugin to topic in another plugin <anchor id="topicsID"/>
<toc link_to="../anotherPluginID/topics.xml#topicsID"...
<anchor> element is placed in the other plugin's toc file as child of a topic previously identified by "to" attribute.
"link_to" attribute isadded to <toc> element previously identified by a "from" attribute.

<insert from="anotherPluginID/topicsID" to="differentPluginID.topicID" />
inserting topics where both "from" and "to" attributes refer to other plugins -
It is not possible to specify linking of a third plugins without involving own TOC

multiple doc.properties file multiple TOC files

1.0	2.0
extension point "org.eclipse.help.contributions"	extension point "org.eclipse.help.toc"
three kinds of XML files describing information sets and views, topics, and actions	one type of XML files describing tables of contents
topic XML file	TOC XML file
topic file description in plugin.xml <extension point="org.eclipse.help.contributions"> <topics name="topics.xml" /> </extension>	TOC file description in plugin.xml <extension point="org.eclipse.help.toc"> <toc file="topics.xml" /> </extension>
<topic> element in topics file <topic id="topic1ID" label="Topic1" href="topic1.html" />	<topic> element in TOC file <topic label="Topic1" href="topic1.html" /> The "id" attribute is no longer used. A topic does not need to be referred to from anywhere else. If topic files are converted to TOC files and "id" attributes are left, help system will ignore them and not generate errors.
<topics> element in topics file <topics id="topics3ID">	<toc> element in TOC file <toc label="Topics3X"> The "id" attribute is no longer required. The TOC is identified by the URL of the file that defines it. e.g. "topics.xml" or "../myPluginID/topics.xml" if referred from another plugin. Each TOC needs a label that describes content of the TOC, and may be visible to the end user if the TOC is included in the documentation library as top level TOC.
information set XML file	TOC XML file designated as primary Any TOC can play a role of the "old" information set by being designated as primary. The primary TOCs can be displayed as top level TOC to the user.
information set file description in plugin.xml <extension point="org.eclipse.help.contributions"> <infoset name="infoset.xml" /> </extension>	primary TOC file description in plugin.xml <extension point="org.eclipse.help.toc"> <toc file="topics.xml" primary="true" /> </extension>
information set <infoset id="myInfoSetID" label="MyInfoSetLabel" >	primary TOC <toc label="MyInfoSetLabel"> The "id" attribute is no longer required. The TOC is identified by the URL of the file that defines it. When TOC is displayed to the user its label plays the same role as the information set label in version 1.0.
standalone information set	primary TOC
information view <infoview id="myInfoViewID" label="MyInfoViewLabel" />	primary TOC <toc label="MyInfoViewLabel"> All primary TOCs appear in the documentation library. They can be linked to other TOCs, and then do not show as top level TOC, but are available as part of another TOC. The "id" attribute is no longer required. The TOC is identified by the URL of the file it is defined in. When TOC is displayed to the user its label plays the same role as the information set label in version 1.0.
actions XML file	- Linking is specified directly in the involved TOC files.
<insert> element in actions file <insert from="topicsID" to="topicID" />	<link> element in one of the linked TOC files <link toc="topics.xml" /> OR <anchor> element in one TOC files and "link_to" attribute in<toc> element in the second TOC file <anchor id="topicsID"/> <toc label="Topics Label" link_to="topics.xml#topicsID" /> "as" attribute is not needed, as location of <link> or <anchor> element uniquely define point of integration. Multiple <anchor> elements can be used to achieve desired order of TOCs linked such they become children of the same topic.
<insert from="anotherPluginID.topicsID" to="topicID" /> inserting topics from another plugin to topic in this plugin	<link toc="../anotherPluginID/topics.xml /> "link" is placed in TOC file as a child of the topic previously identified by the "to" attribute.
<insert from="topicsID" to="anotherPluginID.topicID" /> inserting topics from this plugin to topic in another plugin	<anchor id="topicsID"/> <toc link_to="../anotherPluginID/topics.xml#topicsID"... <anchor> element is placed in the other plugin's toc file as child of a topic previously identified by "to" attribute. "link_to" attribute isadded to <toc> element previously identified by a "from" attribute.
<insert from="anotherPluginID/topicsID" to="differentPluginID.topicID" /> inserting topics where both "from" and "to" attributes refer to other plugins	- It is not possible to specify linking of a third plugins without involving own TOC
multiple doc.properties file	multiple TOC files

The above table shows that both the information set and information view map to the primary TOC. The process for creating is:

A primary TOC should be created for each view. It should be labeled after the view name, and have topics that were inserted immediately under the view as its content. TOCs will be shown to the user as the top level TOC in the documentation library.

Another primary TOC can be created for an information set and named the same as the information set. It should contain newly created topics corresponding to the information views, and links to integrate the TOCs corresponding to the views:

<toc label="MyInfoSetLabel" >
      <topic label="MyInfoView1Label">
           <link toc="view1.xml" />
      </topic>
      <topic label="MyInfoView2Label">
           <link toc="view2.xml" />
      </topic>
</toc>

The end effect will be that this TOC will appear as the top level TOC in the documentation library, and will contain views and their topics in its structure.

Using the TOC corresponding to the information set is optional. If corresponding infoset.xml file is not created (or not used), the documentation library will contains TOCs for the views as the top level TOCs.

EXAMPLE - A plugin defining an information set, information view, and a single topic file, with second plugin contributing more topic files.

The documentation consisted of topics contributed by two plugins. The first plugin also defined an information set, an information view and actions to wire topics into the view. The documentation could have been described in 1.0 syntax as follows:

In plugin 1
topics.xml:

<topics id="allTopicsID">
      <topic id="topic1ID" label="Topic1" href="topic1.html" />
      <topic id="topic2ID" label="Topic2" />
      <topic id="topic3ID" label="Topic3" href="topic3.html" />
</topics>

infoset.xml:

<infoset id="myInfoSetID" label="MyInfoSetLabel" >
<infoview id="myInfoViewID" label="MyInfoViewLabel" />
</infoset>

and actions.xml:

<actions infoview="myInfoViewID">
      <insert from="plugin1.allTopicsID" to="plugin1.myInfoViewID" />
      <insert from="plugin2.topics3ID" to="plugin1.topic2ID" />
      <insert from="plugin2.topics3ID" to="plugin1topic3ID" />
</actions>

In plugin 2
topics2.xml:

<topics id="topics2ID">
<topic id="topic21ID" label="Topic21" href="topic21.html" />
<topic id="topic22ID" label="Topic22" href="topic22.html" />
</topics>

topics3.xml:

<topics id="topics3ID">
<topic id="topic31ID" label="Topic31" href="topic31.html" />
</topics>

The procedure to convert this contribution to 2.0 syntax is as follows:

1. Rename topics.xml to view.xml, as topics.xml defined topic that were inserted directly into the view.
2. Rename the "topics" element to "toc".
3. Add the "label" attribute to the "toc" element in the view.xml. Its value is a label of your old information view.
4. Add "label" attribute to the "toc" element in the topics2.xml and topics3.xml. Use a description of the topics in those files as the attribute value. It will not be visible to the end user.
5. Link topics files together by adding "link" element as a child of Topic2 with attribute "toc" set to relative URL of topics2.xml, and adding "link" element as a child of Topic3 with attribute "toc" set to URL of topics3.xml.
6. Remove your infoset.xml and actions.xml files.
7. You may remove "id" attributes from within your topic.xml file.

Since information set contained only one view, it makes sense not to use the TOC corresponding to the information set. Such TOC would contain only one topic (for the view) and its children.

After conversion you will end up with files:

In plugin 1
view.xml:

<toc label="MyInfoViewLabel">
      <topic label="Topic1" href="topic1.html" />
      <topic label="Topic2" >
           <link toc="../plugin2/topics2.xml" />
      </topic>
      <topic label="Topic3" href="topic3.html">
           <link toc="../plugin2/topics3.xml" />
      </topic>
</toc>

In plugin2
topics2.xml:

<toc label="Topics2X">
<topic label="Topic21" href="topic21.html" />
<topic label="Topic22" href="topic22.html" />
</toc>

topics3.xml:

<toc label="Topics3X">
<topic label="Topic31" href="topic31.html" />
</toc>

The extensions for "org.eclipse.help.contributions" point in plugin.xml that looked like:

<extension point="org.eclipse.help.contributions">
      <infoset name="infoset.xml" />
      <topics name="topics.xml" />
      <actions name="actions.xml" />
</extension>

in plugin1, and in plugin2:

<extension point="org.eclipse.help.contributions">
<topics name="topics2.xml" />
<topics name="topic3.xml" />
</extension>

They need to be replaced with descriptions for new extension for "org.eclipse.help.toc" point, that might be done step by step:

1. Change value of the "point" to org.eclipse.help.toc.
2. Delete information set and action elements
3. Rename "topics" elements to "toc" element and "name" attributes to "file".
4. Change "topics.xml" file attribute value to "view.xml".
5. Add attribute "primary" with value "true" to the toc element pointing to topics.xml.

At the end the extension for the contributions will have a form:

<extension point="org.eclipse.help.toc">
<toc file="view.xml" primary="true" />
</extension>

in plugin.xml of plugin1, and for plugin2 will look:

<extension point="org.eclipse.help.toc">
<toc file="topics2.xml" />
<toc file="topics3.xml" />
</extension>

Advanced Scenarios

Handling topic having different children in each of information views

In 1.0 navigation each view was completely independent from other views, and acted like a name space. Each topic could exist only once in a view, but could be inserted into multiple views. In 2.0 help system, there is no views. In the new help system, a TOC can be linked multiple times by one or many other TOCs. The links are valid across all documentation library.

If in 1.0 navigation, a topic ("topic" element in a topics file, not the html document) existed in multiple views, and there were actions defined, that inserted more topics as descendants of that topic, these actions could have created topic sub-trees that were different between the views. If those actions were converted to links in 2.0 TOC file, the involved topic's sub-tree would be a sum of topics that existed in all of the information views. To avoid this effect, a different topic must be used in all instances where topic's children differed. This can be accomplished by creating a copy of the TOC file containing the given topic. The copies of TOC can still contain a topic pointing to the same HTML document, but the TOCs do not need to be the same. One should link children that were present in one view, and the other copy should link children present in a different view.

Handling standalone information sets

Since it was impossible to link information sets together in 1.0 help system, a component anticipating possibility of having its documentation integrated by another information set would mark its information set as standalone. This version of help system does not require any special action on this component side to cover this scenario. If no other component link to this component TOC, the TOC will be visible as the top level TOCs. If it is linked by another TOC, it will be present inside that TOC structure only.

A component that used topic or topics from another component that defined a standalone Information Set, should avoid this in version 2.0 of help. To include another component's documentation under its own, the component should link a primary TOC of the other component.

Handling single topic inserted from the middle of a topic file

If insert action existed in 1.0 contribution that was inserting a topic from the middle of a topic file, as opposed to inserting all topics of that file by specifying topics id, such insert action cannot be directly translated into a single link in 2.0 navigation. The problem needs to be solved by different way of grouping topics in topic or TOC files. The granularity ot TOC files can be reduces or copies of TOC can be created. The approach taken will depend on a specific circumstances.

Internationalization

The 2.0 help system expects the TOC XML files to be translatable, and will look for the TOC under <plugin install dir>/nl/<locale> directory. If strings from 1.0 help contributions were externalized to property files, they need to be put back into the topics files (now TOC). If translated properties are already available, multiple copies of the TOCs can be created and placed under appropriate locale directories. Each of the TOCs should be filled with string from the corresponding property file.