platform-help-home/migrating.html
Parent Directory
| 
Revision Log
Revision 1.5 -
(download)
(as text)
(annotate)
Fri Apr 5 06:37:39 2002 UTC (7 years, 7 months ago) by kkolosow
Branch: MAIN
Changes since 1.4: +15 -11 lines
Fri Apr 5 06:37:39 2002 UTC (7 years, 7 months ago) by kkolosow
Branch: MAIN
Changes since 1.4: +15 -11 lines
clarify internationalization
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="Description" content="Describes differences between 1.0 and 2.0 navigation and steps to convert 1.0 navigation to 2.0 syntax"> <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> <title>Migrating Help Contributions</title> <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css"> <style type="text/css"> <!-- .oldcode { font-family: monospace; background-color: #FFDDDD; font-size: small;} .newcode { font-family: monospace; background-color: #DDDDFF; font-size: small;} .oldsyntax { background-color: #FFDDDD; font-size: small;} .newsyntax { background-color: #DDDDFF; font-size: small;} --> </style> </head> <body> <h2> Migrating Online Help Contributions from version 1.0 to version 2.0</h2> <a NAME="TOP"></a><a href="#INTRODUCTION">INTRODUCTION</a> <br><a href="#DIFFERENCES">MAPPING BETWEEN 1.0 and 2.0 CONTRIBUTION MECHANISMS</a> <br><a href="#STEPS">EXAMPLE</a> <br><a href="#ADVANCED">ADVANCED CASES</a> <br> <a href="#CHILDREN">Handling topic having different children in each of information views</a> <br> <a href="#STANDALONE">Handling standalone information sets</a> <br> <a href="#MIDDLE">Handling single topic inserted from the middle of a topic file</a> <br> <a href="#INTERNATIONALIZATION">Internationalization</a> <h3> <a NAME="INTRODUCTION"></a>INTRODUCTION</h3> The 2.0 help system concepts are described in <a href="online_help2.0.html">Online Help Changes</a> 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. <p><a href="#TOP">back to top</a> <h3> <a NAME="DIFFERENCES"></a>MAPPING BETWEEN 1.0 and 2.0 CONTRIBUTION MECHANISM</h3> 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. <p>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. <p>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. <p>The following table identifies significant 1.0 help system artifacts and their translation to 2.0 help system concepts. <table BORDER COLS=2 WIDTH="100%" > <caption> </caption> <tr> <td VALIGN=TOP class="oldsyntax"> <center><b><font size=+2>1.0</font></b></center> </td> <td VALIGN=TOP class="newsyntax"> <center><b><font size=+2>2.0</font></b></center> </td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>extension point "org.eclipse.help.contributions"</b></td> <td VALIGN=TOP class="newsyntax"><b>extension point "org.eclipse.help.toc"</b></td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>three kinds of XML files describing information sets and views, topics, and actions</b></td> <td VALIGN=TOP class="newsyntax"><b>one type of XML files describing tables of contents</b></td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>topic XML file</b></td> <td VALIGN=TOP class="newsyntax"><b>TOC XML file</b></td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>topic file description in plugin.xml</b> <br><extension point="org.eclipse.help.contributions"> <br> <topics name="topics.xml" /> <br></extension></td> <td VALIGN=TOP class="newsyntax"><b>TOC file description in plugin.xml</b> <br><extension point="org.eclipse.help.toc"> <br> <toc file="topics.xml" /> <br></extension></td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b><topic> element in topics file</b> <br><topic id="topic1ID" label="Topic1" href="topic1.html" /></td> <td VALIGN=TOP class="newsyntax"><b><topic> element in TOC file</b> <br><topic label="Topic1" href="topic1.html" /> <br>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.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b><topics> element in topics file</b> <br><topics id="topics3ID"></td> <td VALIGN=TOP class="newsyntax"><b><toc> element in TOC file</b> <br><toc label="Topics3X"> <br>The "id" attribute is no longer required. The TOC is identified by the URL of the file that defines it. <br>e.g. "topics.xml" or "../myPluginID/topics.xml" if referred from another plugin. <br>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.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>information set XML file</b></td> <td VALIGN=TOP class="newsyntax"><b>TOC XML file designated as primary</b> <br>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.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>information set file description in plugin.xml</b> <br><extension point="org.eclipse.help.contributions"> <br> <infoset name="infoset.xml" /> <br></extension></td> <td VALIGN=TOP class="newsyntax"><b>primary TOC file description in plugin.xml</b> <br><extension point="org.eclipse.help.toc"> <br> <toc file="topics.xml" primary="true" /> <br></extension></td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>information set</b> <br><infoset id="myInfoSetID" label="MyInfoSetLabel" > <p> </td> <td VALIGN=TOP class="newsyntax"><b>primary TOC</b> <br><toc label="MyInfoSetLabel"> <br>The "id" attribute is no longer required. The TOC is identified by the URL of the file that defines it. <br>When TOC is displayed to the user its label plays the same role as the information set label in version 1.0.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>standalone information set</b></td> <td VALIGN=TOP class="newsyntax"><b>primary TOC</b></td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>information view</b> <br><infoview id="myInfoViewID" label="MyInfoViewLabel" /></td> <td VALIGN=TOP class="newsyntax"><b>primary TOC</b> <br><toc label="MyInfoViewLabel"> <br>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. <br>The "id" attribute is no longer required. The TOC is identified by the URL of the file it is defined in. <br>When TOC is displayed to the user its label plays the same role as the information set label in version 1.0.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>actions XML file</b></td> <td VALIGN=TOP class="newsyntax"><b>-</b> <br>Linking is specified directly in the involved TOC files.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b><insert> element in actions file</b> <br><insert from="topicsID" to="topicID" /></td> <td VALIGN=TOP class="newsyntax"><b><link> element in one of the linked TOC files</b> <br><link toc="topics.xml" /> <br><b>OR</b> <br><b><anchor> element in one TOC files and "link_to" attribute in<toc> element in the second TOC file</b> <br><anchor id="topicsID"/> <br><toc label="Topics Label" link_to="topics.xml#topicsID" /> <br>"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.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b><insert from="anotherPluginID.topicsID" to="topicID" /></b> <br>inserting topics from another plugin to topic in this plugin</td> <td VALIGN=TOP class="newsyntax"><b><link toc="../anotherPluginID/topics.xml /></b> <br>"link" is placed in TOC file as a child of the topic previously identified by the "to" attribute.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b><insert from="topicsID" to="anotherPluginID.topicID" /></b> <br>inserting topics from this plugin to topic in another plugin</td> <td VALIGN=TOP class="newsyntax"><b><anchor id="topicsID"/></b> <br><b><toc link_to="../anotherPluginID/topics.xml#topicsID"... </b> <br><anchor> element is placed in the other plugin's toc file as child of a topic previously identified by "to" attribute. <br>"link_to" attribute isadded to <toc> element previously identified by a "from" attribute.</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b><insert from="anotherPluginID/topicsID" to="differentPluginID.topicID" /></b> <br>inserting topics where both "from" and "to" attributes refer to other plugins</td> <td VALIGN=TOP class="newsyntax"><b>-</b> <br>It is not possible to specify linking of a third plugins without involving own TOC</td> </tr> <tr> <td VALIGN=TOP class="oldsyntax"><b>multiple doc.properties file</b></td> <td VALIGN=TOP class="newsyntax"><b>multiple TOC files</b></td> </tr> </table> <p>The above table shows that both the information set and information view map to the primary TOC. The process for creating is: <p>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. <p>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: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="newcode"><toc label="MyInfoSetLabel" > <br> <topic label="MyInfoView1Label"> <br> <link toc="view1.xml" /> <br> </topic> <br> <topic label="MyInfoView2Label"> <br> <link toc="view2.xml" /> <br> </topic> <br></toc></td> </tr> </table> <p>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. <p>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. <p><a href="#TOP">back to top</a> <h3> <a NAME="STEPS"></a>EXAMPLE - A plugin defining an information set, information view, and a single topic file, with second plugin contributing more topic files.</h3> 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: <p>In plugin 1 <br>topics.xml: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="oldcode"><topics id="allTopicsID"> <br> <topic id="topic1ID" label="Topic1" href="topic1.html" /> <br> <topic id="topic2ID" label="Topic2" /> <br> <topic id="topic3ID" label="Topic3" href="topic3.html" /> <br></topics></td> </tr> </table> <p>infoset.xml: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="oldcode"><infoset id="myInfoSetID" label="MyInfoSetLabel" > <br> <infoview id="myInfoViewID" label="MyInfoViewLabel" /> <br></infoset></td> </tr> </table> <p>and actions.xml: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="oldcode"><actions infoview="myInfoViewID"> <br> <insert from="plugin1.allTopicsID" to="plugin1.myInfoViewID" /> <br> <insert from="plugin2.topics3ID" to="plugin1.topic2ID" /> <br> <insert from="plugin2.topics3ID" to="plugin1topic3ID" /> <br></actions> </td> </tr> </table> <p>In plugin 2 <br>topics2.xml: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="oldcode"><topics id="topics2ID"> <br> <topic id="topic21ID" label="Topic21" href="topic21.html" /> <br> <topic id="topic22ID" label="Topic22" href="topic22.html" /> <br></topics></td> </tr> </table> <p>topics3.xml: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="oldcode"><topics id="topics3ID"> <br> <topic id="topic31ID" label="Topic31" href="topic31.html" /> <br></topics></td> </tr> </table> <p>The procedure to convert this contribution to 2.0 syntax is as follows: <p>1. Rename topics.xml to view.xml, as topics.xml defined topic that were inserted directly into the view. <br>2. Rename the "topics" element to "toc". <br>3. Add the "label" attribute to the "toc" element in the view.xml. Its value is a label of your old information view. <br>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. <br>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. <br>6. Remove your infoset.xml and actions.xml files. <br>7. You may remove "id" attributes from within your topic.xml file. <p>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. <p>After conversion you will end up with files: <p>In plugin 1 <br>view.xml: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="newcode"><toc label="MyInfoViewLabel"> <br> <topic label="Topic1" href="topic1.html" /> <br> <topic label="Topic2" > <br> <link toc="../plugin2/topics2.xml" /> <br> </topic> <br> <topic label="Topic3" href="topic3.html"> <br> <link toc="../plugin2/topics3.xml" /> <br> </topic> <br></toc></td> </tr> </table> <p>In plugin2 <br>topics2.xml: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="newcode"><toc label="Topics2X"> <br> <topic label="Topic21" href="topic21.html" /> <br> <topic label="Topic22" href="topic22.html" /> <br></toc></td> </tr> </table> <p>topics3.xml: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="newcode"><toc label="Topics3X"> <br> <topic label="Topic31" href="topic31.html" /> <br></toc></td> </tr> </table> <p>The extensions for "org.eclipse.help.contributions" point in plugin.xml that looked like: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="oldcode"><extension point="org.eclipse.help.contributions"> <br> <infoset name="infoset.xml" /> <br> <topics name="topics.xml" /> <br> <actions name="actions.xml" /> <br></extension></td> </tr> </table> <p>in plugin1, and in plugin2: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="oldcode"><extension point="org.eclipse.help.contributions"> <br> <topics name="topics2.xml" /> <br> <topics name="topic3.xml" /> <br></extension></td> </tr> </table> <p>They need to be replaced with descriptions for new extension for "org.eclipse.help.toc" point, that might be done step by step: <p>1. Change value of the "point" to org.eclipse.help.toc. <br>2. Delete information set and action elements <br>3. Rename "topics" elements to "toc" element and "name" attributes to "file". <br>4. Change "topics.xml" file attribute value to "view.xml". <br>5. Add attribute "primary" with value "true" to the toc element pointing to topics.xml. <p>At the end the extension for the contributions will have a form: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="newcode"><extension point="org.eclipse.help.toc"> <br> <toc file="view.xml" primary="true" /> <br></extension></td> </tr> </table> <p>in plugin.xml of plugin1, and for plugin2 will look: <br> <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > <tr> <td class="newcode"><extension point="org.eclipse.help.toc"> <br> <toc file="topics2.xml" /> <br> <toc file="topics3.xml" /> <br></extension></td> </tr> </table> <p><a href="#TOP">back to top</a> <h3> <a NAME="ADVANCED"></a>Advanced Scenarios</h3> <h4> <a NAME="CHILDREN"></a>Handling topic having different children in each of information views</h4> 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. <p>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. <h4> <a NAME="STANDALONE"></a>Handling standalone information sets</h4> 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. <p>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. <h4> <a NAME="MIDDLE"></a>Handling single topic inserted from the middle of a topic file</h4> 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. <h4> <a NAME="INTERNATIONALIZATION"></a>Internationalization</h4> The 2.0 help system expects the TOC XML files to be translated, and will look for the TOC under <plugin install dir>/nl/<language>/<country> and <plugin install dir>/nl/<language>/ directories. 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. Since format of property files and XML differ, attention must be paid to encoding of characters. Characters that are not part of ISO 8859-1 encoding and were encoded using \uXXXX format in property files, no longer need to be encoded. Special characters can be encoded using in XML using &#xXX; format. <p><a href="#TOP">back to top</a> </body> </html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |