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