platform-help-home/migrating.html
Parent Directory
| 
Revision Log
Revision 1.8 - (view) (download) (as text)
| 1 : | kkolosow | 1.7 | <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| 2 : | <html> | ||
| 3 : | <head> | ||
| 4 : | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
| 5 : | <meta name="Description" content="Describes differences between 1.0 and 2.0 navigation and steps to convert 1.0 navigation to 2.0 syntax"> | ||
| 6 : | <meta name="GENERATOR" content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]"> | ||
| 7 : | <title>Migrating Help Contributions</title> | ||
| 8 : | <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css"> | ||
| 9 : | <style type="text/css"> | ||
| 10 : | <!-- | ||
| 11 : | .oldcode { font-family: monospace; background-color: #FFDDDD; font-size: small;} | ||
| 12 : | .newcode { font-family: monospace; background-color: #DDDDFF; font-size: small;} | ||
| 13 : | .oldsyntax { background-color: #FFDDDD; font-size: small;} | ||
| 14 : | .newsyntax { background-color: #DDDDFF; font-size: small;} | ||
| 15 : | --> | ||
| 16 : | </style> | ||
| 17 : | </head> | ||
| 18 : | <body> | ||
| 19 : | |||
| 20 : | <h2> | ||
| 21 : | Migrating Online Help Contributions from version 1.0 to version 2.0</h2> | ||
| 22 : | <a NAME="TOP"></a><a href="#INTRODUCTION">INTRODUCTION</a> | ||
| 23 : | <br><a href="#DIFFERENCES">MAPPING BETWEEN 1.0 and 2.0 CONTRIBUTION MECHANISMS</a> | ||
| 24 : | <br><a href="#STEPS">EXAMPLE</a> | ||
| 25 : | <br><a href="#ADVANCED">ADVANCED CASES</a> | ||
| 26 : | <br> <a href="#CHILDREN">Handling topic having | ||
| 27 : | different children in each of information views</a> | ||
| 28 : | <br> <a href="#STANDALONE">Handling standalone | ||
| 29 : | information sets</a> | ||
| 30 : | <br> <a href="#MIDDLE">Handling single topic inserted | ||
| 31 : | from the middle of a topic file</a> | ||
| 32 : | <br> <a href="#INTERNATIONALIZATION">Internationalization</a> | ||
| 33 : | <h3> | ||
| 34 : | <a NAME="INTRODUCTION"></a>INTRODUCTION</h3> | ||
| 35 : | The 2.0 help system concepts are described in <a href="online_help2.0.html">Online | ||
| 36 : | Help Changes</a> document. This document is designated to help converting | ||
| 37 : | existing help contributions created for version 1.0 of help system to form | ||
| 38 : | appropriate for use with the new help system. It contains comparison | ||
| 39 : | of contributions in the old and new help system with suggested conversion | ||
| 40 : | methods. Included is simple example of converting documentation specified | ||
| 41 : | in 1.0 syntax to the 2.0 syntax. | ||
| 42 : | <p><a href="#TOP">back to top</a> | ||
| 43 : | <h3> | ||
| 44 : | <a NAME="DIFFERENCES"></a>MAPPING BETWEEN 1.0 and 2.0 CONTRIBUTION MECHANISM</h3> | ||
| 45 : | First, it is worth mentioning that that documentation content - the HTML | ||
| 46 : | files do not change between the help system versions 1.0 and 2.0. | ||
| 47 : | All documentation written and placed in a zip file does not have to be | ||
| 48 : | edited. The changes affect files describing documentation structure: | ||
| 49 : | information sets, views, topics, insert actions, and their file's descriptor | ||
| 50 : | in plugin.xml. | ||
| 51 : | <p>The largest part of the 1.0 help structure - the topics files, with | ||
| 52 : | tree of "topic" elements, has not changed significantly. They can | ||
| 53 : | be reused in 2.0 syntax with minimal changes. Both information set | ||
| 54 : | files and action files have been eliminated. The information contained | ||
| 55 : | in these files - how to integrate topics has its place inside the TOC files. | ||
| 56 : | <p>The mechanism used for specifying integration of topics existing in | ||
| 57 : | separate TOC available to help system is called linking. Linking | ||
| 58 : | allows for associating a root of one tree with an arbitrary point in another | ||
| 59 : | tree, to create bigger tree. This linking can be specified arbitrarily | ||
| 60 : | in any of the two TOCs involved in the operation. This freedom allows | ||
| 61 : | for any of the two approaches for creating table of contents for a product. | ||
| 62 : | In top-down approach a TOC links the root of another TOC, in bottom-up | ||
| 63 : | a TOC root links to an anchor point defined in another TOC. | ||
| 64 : | <p>The following table identifies significant 1.0 help system artifacts | ||
| 65 : | and their translation to 2.0 help system concepts. | ||
| 66 : | <table BORDER COLS=2 WIDTH="100%" > | ||
| 67 : | <caption> </caption> | ||
| 68 : | |||
| 69 : | <tr> | ||
| 70 : | <td VALIGN=TOP class="oldsyntax"> | ||
| 71 : | <center><b><font size=+2>1.0</font></b></center> | ||
| 72 : | </td> | ||
| 73 : | |||
| 74 : | <td VALIGN=TOP class="newsyntax"> | ||
| 75 : | <center><b><font size=+2>2.0</font></b></center> | ||
| 76 : | </td> | ||
| 77 : | </tr> | ||
| 78 : | |||
| 79 : | <tr> | ||
| 80 : | <td VALIGN=TOP class="oldsyntax"><b>extension point "org.eclipse.help.contributions"</b></td> | ||
| 81 : | |||
| 82 : | <td VALIGN=TOP class="newsyntax"><b>extension point "org.eclipse.help.toc"</b></td> | ||
| 83 : | </tr> | ||
| 84 : | |||
| 85 : | <tr> | ||
| 86 : | <td VALIGN=TOP class="oldsyntax"><b>three kinds of XML files describing | ||
| 87 : | information sets and views, topics, and actions</b></td> | ||
| 88 : | |||
| 89 : | <td VALIGN=TOP class="newsyntax"><b>one type of XML files describing tables | ||
| 90 : | of contents</b></td> | ||
| 91 : | </tr> | ||
| 92 : | |||
| 93 : | <tr> | ||
| 94 : | <td VALIGN=TOP class="oldsyntax"><b>topic XML file</b></td> | ||
| 95 : | |||
| 96 : | <td VALIGN=TOP class="newsyntax"><b>TOC XML file</b></td> | ||
| 97 : | </tr> | ||
| 98 : | |||
| 99 : | <tr> | ||
| 100 : | <td VALIGN=TOP class="oldsyntax"><b>topic file description in plugin.xml</b> | ||
| 101 : | <br><extension point="org.eclipse.help.contributions"> | ||
| 102 : | <br> <topics name="topics.xml" /> | ||
| 103 : | <br></extension></td> | ||
| 104 : | |||
| 105 : | <td VALIGN=TOP class="newsyntax"><b>TOC file description in plugin.xml</b> | ||
| 106 : | <br><extension point="org.eclipse.help.toc"> | ||
| 107 : | <br> <toc file="topics.xml" /> | ||
| 108 : | <br></extension></td> | ||
| 109 : | </tr> | ||
| 110 : | |||
| 111 : | <tr> | ||
| 112 : | <td VALIGN=TOP class="oldsyntax"><b><topic> element in topics file</b> | ||
| 113 : | <br><topic id="topic1ID" label="Topic1" href="topic1.html" /></td> | ||
| 114 : | |||
| 115 : | <td VALIGN=TOP class="newsyntax"><b><topic> element in TOC file</b> | ||
| 116 : | <br><topic label="Topic1" href="topic1.html" /> | ||
| 117 : | <br>The "id" attribute is no longer used. A topic does not need to | ||
| 118 : | be referred to from anywhere else. If topic files are converted to | ||
| 119 : | TOC files and "id" attributes are left, help system will ignore them and | ||
| 120 : | not generate errors.</td> | ||
| 121 : | </tr> | ||
| 122 : | |||
| 123 : | <tr> | ||
| 124 : | <td VALIGN=TOP class="oldsyntax"><b><topics> element in topics file</b> | ||
| 125 : | <br><topics id="topics3ID"></td> | ||
| 126 : | |||
| 127 : | <td VALIGN=TOP class="newsyntax"><b><toc> element in TOC file</b> | ||
| 128 : | <br><toc label="Topics3X"> | ||
| 129 : | <br>The "id" attribute is no longer required. The TOC is identified | ||
| 130 : | by the URL of the file that defines it. | ||
| 131 : | <br>e.g. "topics.xml" or "../myPluginID/topics.xml" if referred from | ||
| 132 : | another plugin. | ||
| 133 : | <br>Each TOC needs a label that describes content of the TOC, and may be | ||
| 134 : | visible to the end user if the TOC is included in the documentation library | ||
| 135 : | as top level TOC.</td> | ||
| 136 : | </tr> | ||
| 137 : | |||
| 138 : | <tr> | ||
| 139 : | <td VALIGN=TOP class="oldsyntax"><b>information set XML file</b></td> | ||
| 140 : | |||
| 141 : | <td VALIGN=TOP class="newsyntax"><b>TOC XML file designated as primary</b> | ||
| 142 : | <br>Any TOC can play a role of the "old" information set by being designated | ||
| 143 : | as primary. The primary TOCs can be displayed as top level TOC to | ||
| 144 : | the user.</td> | ||
| 145 : | </tr> | ||
| 146 : | |||
| 147 : | <tr> | ||
| 148 : | <td VALIGN=TOP class="oldsyntax"><b>information set file description in | ||
| 149 : | plugin.xml</b> | ||
| 150 : | <br><extension point="org.eclipse.help.contributions"> | ||
| 151 : | <br> <infoset name="infoset.xml" /> | ||
| 152 : | <br></extension></td> | ||
| 153 : | |||
| 154 : | <td VALIGN=TOP class="newsyntax"><b>primary TOC file description in plugin.xml</b> | ||
| 155 : | <br><extension point="org.eclipse.help.toc"> | ||
| 156 : | <br> <toc file="topics.xml" primary="true" /> | ||
| 157 : | <br></extension></td> | ||
| 158 : | </tr> | ||
| 159 : | |||
| 160 : | <tr> | ||
| 161 : | <td VALIGN=TOP class="oldsyntax"><b>information set</b> | ||
| 162 : | <br><infoset id="myInfoSetID" label="MyInfoSetLabel" > | ||
| 163 : | <p> </td> | ||
| 164 : | |||
| 165 : | <td VALIGN=TOP class="newsyntax"><b>primary TOC</b> | ||
| 166 : | <br><toc label="MyInfoSetLabel"> | ||
| 167 : | <br>The "id" attribute is no longer required. The TOC is identified | ||
| 168 : | by the URL of the file that defines it. | ||
| 169 : | <br>When TOC is displayed to the user its label plays the same role as | ||
| 170 : | the information set label in version 1.0.</td> | ||
| 171 : | </tr> | ||
| 172 : | |||
| 173 : | <tr> | ||
| 174 : | <td VALIGN=TOP class="oldsyntax"><b>standalone information set</b></td> | ||
| 175 : | |||
| 176 : | <td VALIGN=TOP class="newsyntax"><b>primary TOC</b></td> | ||
| 177 : | </tr> | ||
| 178 : | |||
| 179 : | <tr> | ||
| 180 : | <td VALIGN=TOP class="oldsyntax"><b>information view</b> | ||
| 181 : | <br><infoview id="myInfoViewID" label="MyInfoViewLabel" /></td> | ||
| 182 : | |||
| 183 : | <td VALIGN=TOP class="newsyntax"><b>primary TOC</b> | ||
| 184 : | <br><toc label="MyInfoViewLabel"> | ||
| 185 : | <br>All primary TOCs appear in the documentation library. They can | ||
| 186 : | be linked to other TOCs, and then do not show as top level TOC, but are | ||
| 187 : | available as part of another TOC. | ||
| 188 : | <br>The "id" attribute is no longer required. The TOC is identified | ||
| 189 : | by the URL of the file it is defined in. | ||
| 190 : | <br>When TOC is displayed to the user its label plays the same role as | ||
| 191 : | the information set label in version 1.0.</td> | ||
| 192 : | </tr> | ||
| 193 : | |||
| 194 : | <tr> | ||
| 195 : | <td VALIGN=TOP class="oldsyntax"><b>actions XML file</b></td> | ||
| 196 : | |||
| 197 : | <td VALIGN=TOP class="newsyntax"><b>-</b> | ||
| 198 : | <br>Linking is specified directly in the involved TOC files.</td> | ||
| 199 : | </tr> | ||
| 200 : | |||
| 201 : | <tr> | ||
| 202 : | <td VALIGN=TOP class="oldsyntax"><b><insert> element in actions file</b> | ||
| 203 : | <br><insert from="topicsID" to="topicID" /></td> | ||
| 204 : | |||
| 205 : | <td VALIGN=TOP class="newsyntax"><b><link> element in one of the linked | ||
| 206 : | TOC files</b> | ||
| 207 : | <br><link toc="topics.xml" /> | ||
| 208 : | <br><b>OR</b> | ||
| 209 : | <br><b><anchor> element in one TOC files and "link_to" attribute in<toc> | ||
| 210 : | element in the second TOC file</b> | ||
| 211 : | <br><anchor id="topicsID"/> | ||
| 212 : | <br><toc label="Topics Label" link_to="topics.xml#topicsID" /> | ||
| 213 : | <br>"as" attribute is not needed, as location of <link> or <anchor> | ||
| 214 : | element uniquely define point of integration. Multiple <anchor> | ||
| 215 : | elements can be used to achieve desired order of TOCs linked such they | ||
| 216 : | become children of the same topic.</td> | ||
| 217 : | </tr> | ||
| 218 : | |||
| 219 : | <tr> | ||
| 220 : | <td VALIGN=TOP class="oldsyntax"><b><insert from="anotherPluginID.topicsID" | ||
| 221 : | to="topicID" /></b> | ||
| 222 : | <br>inserting topics from another plugin to topic in this plugin</td> | ||
| 223 : | |||
| 224 : | <td VALIGN=TOP class="newsyntax"><b><link toc="../anotherPluginID/topics.xml | ||
| 225 : | /></b> | ||
| 226 : | <br>"link" is placed in TOC file as a child of the topic previously identified | ||
| 227 : | by the "to" attribute.</td> | ||
| 228 : | </tr> | ||
| 229 : | |||
| 230 : | <tr> | ||
| 231 : | <td VALIGN=TOP class="oldsyntax"><b><insert from="topicsID" to="anotherPluginID.topicID" | ||
| 232 : | /></b> | ||
| 233 : | <br>inserting topics from this plugin to topic in another plugin</td> | ||
| 234 : | |||
| 235 : | <td VALIGN=TOP class="newsyntax"><b><anchor id="topicsID"/></b> | ||
| 236 : | <br><b><toc link_to="../anotherPluginID/topics.xml#topicsID"... </b> | ||
| 237 : | <br><anchor> element is placed in the other plugin's toc file as child | ||
| 238 : | of a topic previously identified by "to" attribute. | ||
| 239 : | <br>"link_to" attribute isadded to <toc> element previously identified | ||
| 240 : | by a "from" attribute.</td> | ||
| 241 : | </tr> | ||
| 242 : | |||
| 243 : | <tr> | ||
| 244 : | <td VALIGN=TOP class="oldsyntax"><b><insert from="anotherPluginID/topicsID" | ||
| 245 : | to="differentPluginID.topicID" /></b> | ||
| 246 : | <br>inserting topics where both "from" and "to" attributes refer to other | ||
| 247 : | plugins</td> | ||
| 248 : | |||
| 249 : | <td VALIGN=TOP class="newsyntax"><b>-</b> | ||
| 250 : | <br>It is not possible to specify linking of a third plugins without involving | ||
| 251 : | own TOC</td> | ||
| 252 : | </tr> | ||
| 253 : | |||
| 254 : | <tr> | ||
| 255 : | <td VALIGN=TOP class="oldsyntax"><b>multiple doc.properties file</b></td> | ||
| 256 : | |||
| 257 : | <td VALIGN=TOP class="newsyntax"><b>multiple TOC files</b></td> | ||
| 258 : | </tr> | ||
| 259 : | </table> | ||
| 260 : | |||
| 261 : | <p>The above table shows that both the information set and information | ||
| 262 : | view map to the primary TOC. The process for creating is: | ||
| 263 : | <p>A primary TOC should be created for each view. It should be labeled | ||
| 264 : | after the view name, and have topics that were inserted immediately under | ||
| 265 : | the view as its content. TOCs will be shown to the user as | ||
| 266 : | the top level TOC in the documentation library. | ||
| 267 : | <p>Another primary TOC can be created for an information set and named | ||
| 268 : | the same as the information set. It should contain newly created | ||
| 269 : | topics corresponding to the information views, and links to integrate the | ||
| 270 : | TOCs corresponding to the views: | ||
| 271 : | <br> | ||
| 272 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 273 : | <tr> | ||
| 274 : | <td class="newcode"><toc label="MyInfoSetLabel" > | ||
| 275 : | <br> <topic label="MyInfoView1Label"> | ||
| 276 : | <br> <link | ||
| 277 : | toc="view1.xml" /> | ||
| 278 : | <br> </topic> | ||
| 279 : | <br> <topic label="MyInfoView2Label"> | ||
| 280 : | <br> <link | ||
| 281 : | toc="view2.xml" /> | ||
| 282 : | <br> </topic> | ||
| 283 : | <br></toc></td> | ||
| 284 : | </tr> | ||
| 285 : | </table> | ||
| 286 : | |||
| 287 : | <p>The end effect will be that this TOC will appear as the top level TOC | ||
| 288 : | in the documentation library, and will contain views and their topics in | ||
| 289 : | its structure. | ||
| 290 : | <p>Using the TOC corresponding to the information set is optional. | ||
| 291 : | If corresponding infoset.xml file is not created (or not used), the documentation | ||
| 292 : | library will contains TOCs for the views as the top level TOCs. | ||
| 293 : | <p><a href="#TOP">back to top</a> | ||
| 294 : | <h3> | ||
| 295 : | <a NAME="STEPS"></a>EXAMPLE - A plugin defining an information set, information | ||
| 296 : | view, and a single topic file, with second plugin contributing more topic | ||
| 297 : | files.</h3> | ||
| 298 : | The documentation consisted of topics contributed by two plugins. | ||
| 299 : | The first plugin also defined an information set, an information view and | ||
| 300 : | actions to wire topics into the view. The documentation could | ||
| 301 : | have been described in 1.0 syntax as follows: | ||
| 302 : | <p>In plugin 1 | ||
| 303 : | <br>topics.xml: | ||
| 304 : | <br> | ||
| 305 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 306 : | <tr> | ||
| 307 : | <td class="oldcode"><topics id="allTopicsID"> | ||
| 308 : | <br> <topic id="topic1ID" label="Topic1" | ||
| 309 : | href="topic1.html" /> | ||
| 310 : | <br> <topic id="topic2ID" label="Topic2" | ||
| 311 : | /> | ||
| 312 : | <br> <topic id="topic3ID" label="Topic3" | ||
| 313 : | href="topic3.html" /> | ||
| 314 : | <br></topics></td> | ||
| 315 : | </tr> | ||
| 316 : | </table> | ||
| 317 : | |||
| 318 : | <p>infoset.xml: | ||
| 319 : | <br> | ||
| 320 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 321 : | <tr> | ||
| 322 : | <td class="oldcode"><infoset id="myInfoSetID" label="MyInfoSetLabel" | ||
| 323 : | > | ||
| 324 : | <br> <infoview id="myInfoViewID" label="MyInfoViewLabel" | ||
| 325 : | /> | ||
| 326 : | <br></infoset></td> | ||
| 327 : | </tr> | ||
| 328 : | </table> | ||
| 329 : | |||
| 330 : | <p>and actions.xml: | ||
| 331 : | <br> | ||
| 332 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 333 : | <tr> | ||
| 334 : | <td class="oldcode"><actions infoview="myInfoViewID"> | ||
| 335 : | <br> <insert from="plugin1.allTopicsID" | ||
| 336 : | to="plugin1.myInfoViewID" /> | ||
| 337 : | <br> <insert from="plugin2.topics3ID" | ||
| 338 : | to="plugin1.topic2ID" /> | ||
| 339 : | <br> <insert from="plugin2.topics3ID" | ||
| 340 : | to="plugin1topic3ID" /> | ||
| 341 : | <br></actions> </td> | ||
| 342 : | </tr> | ||
| 343 : | </table> | ||
| 344 : | |||
| 345 : | <p>In plugin 2 | ||
| 346 : | <br>topics2.xml: | ||
| 347 : | <br> | ||
| 348 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 349 : | <tr> | ||
| 350 : | <td class="oldcode"><topics id="topics2ID"> | ||
| 351 : | <br> <topic id="topic21ID" label="Topic21" | ||
| 352 : | href="topic21.html" /> | ||
| 353 : | <br> <topic id="topic22ID" label="Topic22" | ||
| 354 : | href="topic22.html" /> | ||
| 355 : | <br></topics></td> | ||
| 356 : | </tr> | ||
| 357 : | </table> | ||
| 358 : | |||
| 359 : | <p>topics3.xml: | ||
| 360 : | <br> | ||
| 361 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 362 : | <tr> | ||
| 363 : | <td class="oldcode"><topics id="topics3ID"> | ||
| 364 : | <br> <topic id="topic31ID" label="Topic31" | ||
| 365 : | href="topic31.html" /> | ||
| 366 : | <br></topics></td> | ||
| 367 : | </tr> | ||
| 368 : | </table> | ||
| 369 : | |||
| 370 : | <p>The procedure to convert this contribution to 2.0 syntax is as follows: | ||
| 371 : | <p>1. Rename topics.xml to view.xml, as topics.xml defined topic | ||
| 372 : | that were inserted directly into the view. | ||
| 373 : | <br>2. Rename the "topics" element to "toc". | ||
| 374 : | <br>3. Add the "label" attribute to the "toc" element in the view.xml. | ||
| 375 : | Its value is a label of your old information view. | ||
| 376 : | <br>4. Add "label" attribute to the "toc" element in the topics2.xml | ||
| 377 : | and topics3.xml. Use a description of the topics in those files as | ||
| 378 : | the attribute value. It will not be visible to the end user. | ||
| 379 : | <br>5. Link topics files together by adding "link" element as a child | ||
| 380 : | of Topic2 with attribute "toc" set to relative URL of topics2.xml, and | ||
| 381 : | adding "link" element as a child of Topic3 with attribute "toc" set to | ||
| 382 : | URL of topics3.xml. | ||
| 383 : | <br>6. Remove your infoset.xml and actions.xml files. | ||
| 384 : | <br>7. You may remove "id" attributes from within your topic.xml | ||
| 385 : | file. | ||
| 386 : | <p>Since information set contained only one view, it makes sense not to | ||
| 387 : | use the TOC corresponding to the information set. Such TOC would | ||
| 388 : | contain only one topic (for the view) and its children. | ||
| 389 : | <p>After conversion you will end up with files: | ||
| 390 : | <p>In plugin 1 | ||
| 391 : | <br>view.xml: | ||
| 392 : | <br> | ||
| 393 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 394 : | <tr> | ||
| 395 : | <td class="newcode"><toc label="MyInfoViewLabel"> | ||
| 396 : | <br> <topic label="Topic1" href="topic1.html" | ||
| 397 : | /> | ||
| 398 : | <br> <topic label="Topic2" > | ||
| 399 : | <br> <link | ||
| 400 : | toc="../plugin2/topics2.xml" /> | ||
| 401 : | <br> </topic> | ||
| 402 : | <br> <topic label="Topic3" href="topic3.html"> | ||
| 403 : | <br> <link | ||
| 404 : | toc="../plugin2/topics3.xml" /> | ||
| 405 : | <br> </topic> | ||
| 406 : | <br></toc></td> | ||
| 407 : | </tr> | ||
| 408 : | </table> | ||
| 409 : | |||
| 410 : | <p>In plugin2 | ||
| 411 : | <br>topics2.xml: | ||
| 412 : | <br> | ||
| 413 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 414 : | <tr> | ||
| 415 : | <td class="newcode"><toc label="Topics2X"> | ||
| 416 : | <br> <topic label="Topic21" href="topic21.html" | ||
| 417 : | /> | ||
| 418 : | <br> <topic label="Topic22" href="topic22.html" | ||
| 419 : | /> | ||
| 420 : | <br></toc></td> | ||
| 421 : | </tr> | ||
| 422 : | </table> | ||
| 423 : | |||
| 424 : | <p>topics3.xml: | ||
| 425 : | <br> | ||
| 426 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 427 : | <tr> | ||
| 428 : | <td class="newcode"><toc label="Topics3X"> | ||
| 429 : | <br> <topic label="Topic31" href="topic31.html" | ||
| 430 : | /> | ||
| 431 : | <br></toc></td> | ||
| 432 : | </tr> | ||
| 433 : | </table> | ||
| 434 : | |||
| 435 : | <p>The extensions for "org.eclipse.help.contributions" point in plugin.xml | ||
| 436 : | that looked like: | ||
| 437 : | <br> | ||
| 438 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 439 : | <tr> | ||
| 440 : | <td class="oldcode"><extension point="org.eclipse.help.contributions"> | ||
| 441 : | <br> <infoset name="infoset.xml" /> | ||
| 442 : | <br> <topics name="topics.xml" /> | ||
| 443 : | <br> <actions name="actions.xml" /> | ||
| 444 : | <br></extension></td> | ||
| 445 : | </tr> | ||
| 446 : | </table> | ||
| 447 : | |||
| 448 : | <p>in plugin1, and in plugin2: | ||
| 449 : | <br> | ||
| 450 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 451 : | <tr> | ||
| 452 : | <td class="oldcode"><extension point="org.eclipse.help.contributions"> | ||
| 453 : | <br> <topics name="topics2.xml" /> | ||
| 454 : | <br> <topics name="topic3.xml" /> | ||
| 455 : | <br></extension></td> | ||
| 456 : | </tr> | ||
| 457 : | </table> | ||
| 458 : | |||
| 459 : | <p>They need to be replaced with descriptions for new extension for "org.eclipse.help.toc" | ||
| 460 : | point, that might be done step by step: | ||
| 461 : | <p>1. Change value of the "point" to org.eclipse.help.toc. | ||
| 462 : | <br>2. Delete information set and action elements | ||
| 463 : | <br>3. Rename "topics" elements to "toc" element and "name" attributes | ||
| 464 : | to "file". | ||
| 465 : | <br>4. Change "topics.xml" file attribute value to "view.xml". | ||
| 466 : | <br>5. Add attribute "primary" with value "true" to the toc element | ||
| 467 : | pointing to topics.xml. | ||
| 468 : | <p>At the end the extension for the contributions will have a form: | ||
| 469 : | <br> | ||
| 470 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 471 : | <tr> | ||
| 472 : | <td class="newcode"><extension point="org.eclipse.help.toc"> | ||
| 473 : | <br> <toc file="view.xml" primary="true" /> | ||
| 474 : | <br></extension></td> | ||
| 475 : | </tr> | ||
| 476 : | </table> | ||
| 477 : | |||
| 478 : | <p>in plugin.xml of plugin1, and for plugin2 will look: | ||
| 479 : | <br> | ||
| 480 : | <table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" > | ||
| 481 : | <tr> | ||
| 482 : | <td class="newcode"><extension point="org.eclipse.help.toc"> | ||
| 483 : | <br> <toc file="topics2.xml" /> | ||
| 484 : | <br> <toc file="topics3.xml" /> | ||
| 485 : | <br></extension></td> | ||
| 486 : | </tr> | ||
| 487 : | </table> | ||
| 488 : | |||
| 489 : | <p><a href="#TOP">back to top</a> | ||
| 490 : | <h3> | ||
| 491 : | <a NAME="ADVANCED"></a>Advanced Scenarios</h3> | ||
| 492 : | |||
| 493 : | <h4> | ||
| 494 : | <a NAME="CHILDREN"></a>Handling topic having different children in each | ||
| 495 : | of information views</h4> | ||
| 496 : | In 1.0 navigation each view was completely independent from other views, | ||
| 497 : | and acted like a name space. Each topic could exist only once in | ||
| 498 : | a view, but could be inserted into multiple views. In 2.0 help system, | ||
| 499 : | there is no views. In the new help system, a TOC can be linked multiple | ||
| 500 : | times by one or many other TOCs. The links are valid across all documentation | ||
| 501 : | library. | ||
| 502 : | <p>If in 1.0 navigation, a topic ("topic" element in a topics file, not | ||
| 503 : | the html document) existed in multiple views, and there were actions defined, | ||
| 504 : | that inserted more topics as descendants of that topic, these actions could | ||
| 505 : | have created topic sub-trees that were different between the views. | ||
| 506 : | If those actions were converted to links in 2.0 TOC file, the involved | ||
| 507 : | topic's sub-tree would be a sum of topics that existed in all of the information | ||
| 508 : | views. To avoid this effect, a different topic must be used | ||
| 509 : | in all instances where topic's children differed. This can be accomplished | ||
| 510 : | by creating a copy of the TOC file containing the given topic. The | ||
| 511 : | copies of TOC can still contain a topic pointing to the same HTML document, | ||
| 512 : | but the TOCs do not need to be the same. One should link children | ||
| 513 : | that were present in one view, and the other copy should link children | ||
| 514 : | present in a different view. | ||
| 515 : | <h4> | ||
| 516 : | <a NAME="STANDALONE"></a>Handling standalone information sets</h4> | ||
| 517 : | Since it was impossible to link information sets together in 1.0 help system, | ||
| 518 : | a component anticipating possibility of having its documentation integrated | ||
| 519 : | by another information set would mark its information set as standalone. | ||
| 520 : | This version of help system does not require any special action on this | ||
| 521 : | component side to cover this scenario. If no other component link | ||
| 522 : | to this component TOC, the TOC will be visible as the top level TOCs. | ||
| 523 : | If it is linked by another TOC, it will be present inside that TOC structure | ||
| 524 : | only. | ||
| 525 : | <p>A component that used topic or topics from another component that defined | ||
| 526 : | a standalone Information Set, should avoid this in version 2.0 of help. | ||
| 527 : | To include another component's documentation under its own, the component | ||
| 528 : | should link a primary TOC of the other component. | ||
| 529 : | <h4> | ||
| 530 : | <a NAME="MIDDLE"></a>Handling single topic inserted from the middle of | ||
| 531 : | a topic file</h4> | ||
| 532 : | If insert action existed in 1.0 contribution that was inserting a topic | ||
| 533 : | from the middle of a topic file, as opposed to inserting all topics of | ||
| 534 : | that file by specifying topics id, such insert action cannot be directly | ||
| 535 : | translated into a single link in 2.0 navigation. The problem needs | ||
| 536 : | to be solved by different way of grouping topics in topic or TOC files. | ||
| 537 : | The granularity ot TOC files can be reduces or copies of TOC can be created. | ||
| 538 : | The approach taken will depend on a specific circumstances. | ||
| 539 : | <h4> | ||
| 540 : | <a NAME="INTERNATIONALIZATION"></a>Internationalization</h4> | ||
| 541 : | The 2.0 help system expects the TOC XML files to be translated, and will | ||
| 542 : | look for the TOC under <plugin install dir>/nl/<language>/<country> | ||
| 543 : | and <plugin install dir>/nl/<language>/ directories. If strings | ||
| 544 : | from 1.0 help contributions were externalized to property files, they need | ||
| 545 : | to be put back into the topics files (now TOC). If translated properties | ||
| 546 : | are already available, multiple copies of the TOCs can be created and placed | ||
| 547 : | under appropriate locale directories. Each of the TOCs should be | ||
| 548 : | filled with string from the corresponding property file. Since format | ||
| 549 : | of property files and XML differ, attention must be paid to encoding of | ||
| 550 : | characters. Characters that are not part of ISO 8859-1 encoding and | ||
| 551 : | were encoded using \uXXXX format in property files, no longer need to be | ||
| 552 : | encoded. Special characters can be encoded using in XML using &#xXX; | ||
| 553 : | format. | ||
| 554 : | <p> | ||
| 555 : | When escaping special characters such as '\n', rules for XML PCDATA sections apply now, instead of rules for Java | ||
| 556 : | properties. | ||
| 557 : | You can use &#x0A; or just have multiple lines in the <description> element. | ||
| 558 : | </p> | ||
| 559 : | |||
| 560 : | |||
| 561 : | <p><a href="#TOP">back to top</a> | ||
| 562 : | </body> | ||
| 563 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |