platform-help-home/online_help2.0.html
Parent Directory
| 
Revision Log
Revision 1.4 - (view) (download) (as text)
| 1 : | dbirsan | 1.1 | <!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> |
| 2 : | <html> | ||
| 3 : | <head> | ||
| 4 : | |||
| 5 : | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
| 6 : | |||
| 7 : | <meta http-equiv="Content-Language" content="en-us"> | ||
| 8 : | |||
| 9 : | <title>Eclipse online help 2.0 changes</title> | ||
| 10 : | </head> | ||
| 11 : | <body> | ||
| 12 : | |||
| 13 : | <h1> ONLINE HELP CHANGES</h1> | ||
| 14 : | <i>(First draft: Nov 13, 2001</i>)<br> | ||
| 15 : | <br> | ||
| 16 : | Early adopters of the eclipse help system version 1.0 have provided considerable | ||
| 17 : | feedback on the contribution mechanism for online help and there seems | ||
| 18 : | to be a consensus on the following as direction for further work: | ||
| 19 : | <ul> | ||
| 20 : | |||
| 21 : | <li> documentation pluggability is great, don't drop this feature</li> | ||
| 22 : | |||
| 23 : | <li> need a simpler mechanism to plug-in the documentation</li> | ||
| 24 : | |||
| 25 : | </ul> | ||
| 26 : | As such, the proposed changes are meant to simplify the help contributions | ||
| 27 : | mechanism, to allow for simple migration from R1.0 and not to introduce | ||
| 28 : | radically new concepts.<br> | ||
| 29 : | <br> | ||
| 30 : | |||
| 31 : | <h2>CONCEPTS<br> | ||
| 32 : | </h2> | ||
| 33 : | This section describes in very general terms the basics of the eclipse | ||
| 34 : | online documentation.<br> | ||
| 35 : | <br> | ||
| 36 : | Eclipse-based products are made up of a number of plugins, each plugin contributing | ||
| 37 : | kkolosow | 1.4 | some function, and/or documentation. Documentation consists of two parts: the actual |
| 38 : | HTML files that are stored inside a ZIP files and the corresponding table of contents | ||
| 39 : | (TOC) stored in XML format in Eclipse plugins. Documentation | ||
| 40 : | dbirsan | 1.1 | is, thus, distributed across plugins and comes together as an integrated documentation |
| 41 : | library at runtime. Tables of contents across all plugins are usually integrated | ||
| 42 : | by linking them to one another to form larger, more product centric view | ||
| 43 : | of the documentation. Most often a plugin defines a primary table of contents | ||
| 44 : | to which other plugins integrate their own table of contents contributions. | ||
| 45 : | <br> | ||
| 46 : | Tables of contents are really the unit of work, the building blocks of the | ||
| 47 : | documentation navigation. Tables of contents can link any other table of contents, | ||
| 48 : | and can be linked to any other table of contents that allows linking. After | ||
| 49 : | all the table of contents linking has been performed some tables of contents | ||
| 50 : | are said to be integrated and some not. Those that are not integrated are | ||
| 51 : | discarded and the library only contains the integrated tables of contents. | ||
| 52 : | <br> | ||
| 53 : | <br> | ||
| 54 : | A table of contents is considered to be integrated if:<br> | ||
| 55 : | |||
| 56 : | <ul> | ||
| 57 : | |||
| 58 : | <li>it is primary</li> | ||
| 59 : | |||
| 60 : | <li>it is linked to an integrated table of contents<br> | ||
| 61 : | </li> | ||
| 62 : | |||
| 63 : | </ul> | ||
| 64 : | A plugin indicates its desired integration of a table of contents by tagging | ||
| 65 : | it as "primary" or not:<br> | ||
| 66 : | |||
| 67 : | <ul> | ||
| 68 : | |||
| 69 : | <li>a table of contents is not tagged as primary when it is meant to be | ||
| 70 : | integrated into another table of contents</li> | ||
| 71 : | |||
| 72 : | <li>a table of contents should be tagged as primary when it is complete | ||
| 73 : | by itself and is not related to other table of contents, or when it is meant | ||
| 74 : | to be the master toc, the skeleton to which other toc's will integrate<br> | ||
| 75 : | </li> | ||
| 76 : | |||
| 77 : | </ul> | ||
| 78 : | Clearly, a primary table of contents can link to other (primary or | ||
| 79 : | not) tables of contents and can link other tables of contents to it. So, tagging | ||
| 80 : | a TOC primary or not only declares an integration intention, not the final | ||
| 81 : | outcome.<br> | ||
| 82 : | <br> | ||
| 83 : | Finally, the set of tables of contents forming the documentation library | ||
| 84 : | is the set of all primary tables of contents that are not linked to another | ||
| 85 : | integrated table of contents. In general it is the set of all the primary | ||
| 86 : | tables of contents, but sometimes, when some primary table of contents is | ||
| 87 : | linked (directly or indirectly) into another primary table of contents then | ||
| 88 : | it is no longer presented as a top level TOC.<br> | ||
| 89 : | <br> | ||
| 90 : | |||
| 91 : | <h2>CHANGES</h2> | ||
| 92 : | |||
| 93 : | <p>At a glance, here are the main changes: </p> | ||
| 94 : | |||
| 95 : | <ul> | ||
| 96 : | |||
| 97 : | <li> Removed</li> | ||
| 98 : | |||
| 99 : | <ul> | ||
| 100 : | |||
| 101 : | <li> information sets (infosets)</li> | ||
| 102 : | |||
| 103 : | <li> information views (infoviews)</li> | ||
| 104 : | |||
| 105 : | <li> actions</li> | ||
| 106 : | |||
| 107 : | <li> topic ids's</li> | ||
| 108 : | |||
| 109 : | <li> properties files: doc.properties and context.properties</li> | ||
| 110 : | |||
| 111 : | </ul> | ||
| 112 : | |||
| 113 : | <li> Unchanged:</li> | ||
| 114 : | |||
| 115 : | <ul> | ||
| 116 : | |||
| 117 : | <li> html help content still goes into doc.zip or unpacked in the plugin | ||
| 118 : | dir</li> | ||
| 119 : | |||
| 120 : | <li> pluggability (i.e. documentation and navigation can stay in the same | ||
| 121 : | plugins): plugins contribute documentation and corresponding navigation structure(s), | ||
| 122 : | that will be merged at runtime into an eclipse-wide documentation.</li> | ||
| 123 : | |||
| 124 : | </ul> | ||
| 125 : | |||
| 126 : | <li> Slightly changed</li> | ||
| 127 : | |||
| 128 : | <ul> | ||
| 129 : | |||
| 130 : | <li> topics.xml files are now toc.xml files</li> | ||
| 131 : | |||
| 132 : | <li> the extension point for contributing help</li> | ||
| 133 : | |||
| 134 : | </ul> | ||
| 135 : | |||
| 136 : | <li> New</li> | ||
| 137 : | |||
| 138 : | <ul> | ||
| 139 : | |||
| 140 : | <li>document/web centric approach to building tables of contents using | ||
| 141 : | linking of smaller, distributed tables of contents</li> | ||
| 142 : | |||
| 143 : | <li> href/URL based mechanism for naming any help resource, including | ||
| 144 : | navigation</li> | ||
| 145 : | |||
| 146 : | </ul> | ||
| 147 : | |||
| 148 : | </ul> | ||
| 149 : | The above suggests that migrating from version 1.0 should be straightforward, | ||
| 150 : | as the html help content (doc.zip) does not change, the topics.xml files | ||
| 151 : | are also almost identical and the modularization of documentation across | ||
| 152 : | plugins can stay the same. There will be a separate document describing migration | ||
| 153 : | steps, tips, and examples. | ||
| 154 : | <p> <br> | ||
| 155 : | </p> | ||
| 156 : | |||
| 157 : | <h2> SCENARIOS</h2> | ||
| 158 : | It helps to look at a few scenarios to understand how help contributions | ||
| 159 : | work. | ||
| 160 : | <h4> Scenario 1: very basic</h4> | ||
| 161 : | The simplest case is when there is exactly one documentation plugin that | ||
| 162 : | consists of a doc.zip and the associated table of contents. The table of | ||
| 163 : | contents should be declared primary, as it makes sense to be standalone. | ||
| 164 : | |||
| 165 : | <p>Here are the files: </p> | ||
| 166 : | |||
| 167 : | <p>plugin.xml </p> | ||
| 168 : | |||
| 169 : | <div align="Right"> | ||
| 170 : | <table border="1" cellpadding="0" width="100%"> | ||
| 171 : | <caption><br> | ||
| 172 : | |||
| 173 : | <div align="Right"></div> | ||
| 174 : | </caption><tbody> | ||
| 175 : | |||
| 176 : | </tbody> <tbody> | ||
| 177 : | <tr> | ||
| 178 : | <td width="100%" bgcolor="#c0c0c0"> | ||
| 179 : | <div style="line-height: 100%; "><font size="-1"><plugin id="MyPlugin"></font></div> | ||
| 180 : | |||
| 181 : | <blockquote> | ||
| 182 : | <div style="line-height: 100%; "><font size="-1"><extension point="org.eclipse.help.toc"></font></div> | ||
| 183 : | |||
| 184 : | <blockquote> | ||
| 185 : | <div style="line-height: 100%; "><font size="-1"><toc file="toc.xml" | ||
| 186 : | primary="<b>true</b>" /></font></div> | ||
| 187 : | </blockquote> | ||
| 188 : | |||
| 189 : | <div style="line-height: 100%; "><font size="-1"></extension></font></div> | ||
| 190 : | </blockquote> | ||
| 191 : | |||
| 192 : | <div style="line-height: 100%; "><font size="-1"></plugin></font></div> | ||
| 193 : | </td> | ||
| 194 : | </tr> | ||
| 195 : | |||
| 196 : | </tbody> | ||
| 197 : | </table> | ||
| 198 : | </div> | ||
| 199 : | toc.xml | ||
| 200 : | <div align="Right"> | ||
| 201 : | <table border="1" cellpadding="0" width="100%"> | ||
| 202 : | <caption><br> | ||
| 203 : | |||
| 204 : | <div align="Right"></div> | ||
| 205 : | </caption><tbody> | ||
| 206 : | |||
| 207 : | </tbody> <tbody> | ||
| 208 : | <tr> | ||
| 209 : | <td width="100%" bgcolor="#c0c0c0"> | ||
| 210 : | <div style="line-height: 100%; "><font size="-1"><toc label="My | ||
| 211 : | Plugin Documentation"></font></div> | ||
| 212 : | |||
| 213 : | <blockquote> | ||
| 214 : | <div style="line-height: 100%; "><font size="-1"><topic label="Compiling" | ||
| 215 : | href="docs/compile.html"></font></div> | ||
| 216 : | |||
| 217 : | <blockquote> | ||
| 218 : | <div style="line-height: 100%; "><font size="-1"><topic label="Java | ||
| 219 : | files" href="docs/java.html"/.></font></div> | ||
| 220 : | |||
| 221 : | <div style="line-height: 100%; "><font size="-1"><topic label="C++ | ||
| 222 : | files" href="docs/cpp.html"/></font></div> | ||
| 223 : | </blockquote> | ||
| 224 : | |||
| 225 : | <div style="line-height: 100%; "><font size="-1"></topic></font></div> | ||
| 226 : | </blockquote> | ||
| 227 : | |||
| 228 : | <div style="line-height: 100%; "><font size="-1"></toc></font></div> | ||
| 229 : | </td> | ||
| 230 : | </tr> | ||
| 231 : | |||
| 232 : | </tbody> | ||
| 233 : | </table> | ||
| 234 : | </div> | ||
| 235 : | The doc.zip file contains docs/compile.html, docs/java.html and docs/cpp.html | ||
| 236 : | (and any images used). | ||
| 237 : | <p>The Help library consists of the following navigation structure</p> | ||
| 238 : | |||
| 239 : | <center> | ||
| 240 : | <table border="1" cellpadding="0" width="100%" bgcolor="#c0c0c0"> | ||
| 241 : | <caption><br> | ||
| 242 : | |||
| 243 : | <center></center> | ||
| 244 : | </caption><tbody> | ||
| 245 : | |||
| 246 : | </tbody> <tbody> | ||
| 247 : | <tr> | ||
| 248 : | <td width="808" height="137"><font size="-1"> | ||
| 249 : | Compiling</font> | ||
| 250 : | <p><font size="-1"> | ||
| 251 : | Java files</font> </p> | ||
| 252 : | |||
| 253 : | <p><font size="-1"> | ||
| 254 : | C++ files</font></p> | ||
| 255 : | </td> | ||
| 256 : | </tr> | ||
| 257 : | |||
| 258 : | </tbody> | ||
| 259 : | </table> | ||
| 260 : | </center> | ||
| 261 : | |||
| 262 : | <h4> Scenario 2: basic</h4> | ||
| 263 : | There are a few documentation plugins, none being aware of the others | ||
| 264 : | existence (i.e. TOC's are standalone). In this case, each table of contents | ||
| 265 : | is tagged as a "primary" and the library consists of the collection of all | ||
| 266 : | the defined TOC's. | ||
| 267 : | <h4> Scenario 3: top-down integration</h4> | ||
| 268 : | A common scenario is to build an eclipse-based product and have the navigation | ||
| 269 : | distributed in a number of plugins, with a master plugin providing the | ||
| 270 : | navigation skeleton. The master table of contents file would then | ||
| 271 : | include the other tables of contents at certain point and is marked as primary. | ||
| 272 : | |||
| 273 : | <p>The basic markup is to add an <<b>link toc="../another_pluginID/another_toc_section.xml"></b> | ||
| 274 : | at the desired point in a table of contents. This basically links (integrates) | ||
| 275 : | the "another_toc.xml" navigation. The effect of this is that the help system | ||
| 276 : | now has just one big table of contents that is made up of smaller ones. </p> | ||
| 277 : | |||
| 278 : | <p>Here are the files: </p> | ||
| 279 : | |||
| 280 : | <p>plugin.xml in PluginA and PluginB </p> | ||
| 281 : | |||
| 282 : | <div align="Right"> | ||
| 283 : | <table border="1" cellpadding="0" width="100%"> | ||
| 284 : | <caption><br> | ||
| 285 : | |||
| 286 : | <div align="Right"></div> | ||
| 287 : | </caption><tbody> | ||
| 288 : | |||
| 289 : | </tbody> <tbody> | ||
| 290 : | <tr> | ||
| 291 : | <td bgcolor="#c0c0c0"> | ||
| 292 : | <div style="line-height: 100%; "><font size="-1"><plugin | ||
| 293 : | id="PluginA"></font></div> | ||
| 294 : | |||
| 295 : | <blockquote> | ||
| 296 : | |||
| 297 : | <div style="line-height: 100%; "><font size="-1"><extension | ||
| 298 : | point="org.eclipse.help.toc"></font></div> | ||
| 299 : | |||
| 300 : | <blockquote> | ||
| 301 : | |||
| 302 : | <div style="line-height: 100%; "><font size="-1"><toc | ||
| 303 : | file="toc.xml" type="<b>toc</b>"/></font></div> | ||
| 304 : | </blockquote> | ||
| 305 : | |||
| 306 : | <div style="line-height: 100%; "><font size="-1"></extension></font></div> | ||
| 307 : | </blockquote> | ||
| 308 : | |||
| 309 : | <div style="line-height: 100%; "><font size="-1"></plugin></font></div> | ||
| 310 : | </td> | ||
| 311 : | <td bgcolor="#c0c0c0"> | ||
| 312 : | |||
| 313 : | <div style="line-height: 100%; "><font size="-1"><plugin | ||
| 314 : | id="PluginB"></font></div> | ||
| 315 : | |||
| 316 : | <blockquote> | ||
| 317 : | |||
| 318 : | <div style="line-height: 100%; "><font size="-1"><extension | ||
| 319 : | point="org.eclipse.help.toc"></font></div> | ||
| 320 : | |||
| 321 : | <blockquote> | ||
| 322 : | |||
| 323 : | <div style="line-height: 100%; "><font size="-1"><toc | ||
| 324 : | file="toc.xml"/></font></div> | ||
| 325 : | </blockquote> | ||
| 326 : | |||
| 327 : | |||
| 328 : | <div style="line-height: 100%; "><font size="-1"></extension></font></div> | ||
| 329 : | </blockquote> | ||
| 330 : | |||
| 331 : | |||
| 332 : | <div style="line-height: 100%; "><font size="-1"></plugin></font></div> | ||
| 333 : | </td> | ||
| 334 : | </tr> | ||
| 335 : | |||
| 336 : | </tbody> | ||
| 337 : | |||
| 338 : | </table> | ||
| 339 : | </div> | ||
| 340 : | toc.xml in PluginA and PluginB | ||
| 341 : | |||
| 342 : | <div align="Right"><br> | ||
| 343 : | |||
| 344 : | <table border="1" cellpadding="0" width="100%"> | ||
| 345 : | <caption><br> | ||
| 346 : | |||
| 347 : | <div align="Right"></div> | ||
| 348 : | </caption><tbody> | ||
| 349 : | |||
| 350 : | </tbody> <tbody> | ||
| 351 : | <tr> | ||
| 352 : | <td width="50%" bgcolor="#c0c0c0"> | ||
| 353 : | |||
| 354 : | <div style="line-height: 100%; "><font size="-1"><toc | ||
| 355 : | label="PluginA Documentation"></font></div> | ||
| 356 : | |||
| 357 : | |||
| 358 : | <blockquote> | ||
| 359 : | |||
| 360 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 361 : | <topic label="Compiling" href="docs/compile.html"></font></div> | ||
| 362 : | |||
| 363 : | |||
| 364 : | <blockquote> | ||
| 365 : | |||
| 366 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 367 : | <topic label="Java files" href="docs/java.html"/></font></div> | ||
| 368 : | |||
| 369 : | |||
| 370 : | <div style="line-height: 100%; "><b><font size="-1"> | ||
| 371 : | <link toc="../PluginB/toc.xml"/></font></b></div> | ||
| 372 : | |||
| 373 : | |||
| 374 : | <p style="line-height: 100%; "><font size="-1"> | ||
| 375 : | <topic label="C++ files" href="docs/cpp.html"/></font></p> | ||
| 376 : | </blockquote> | ||
| 377 : | |||
| 378 : | |||
| 379 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 380 : | </topic></font></div> | ||
| 381 : | </blockquote> | ||
| 382 : | |||
| 383 : | |||
| 384 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 385 : | </topic></font></div> | ||
| 386 : | </td> | ||
| 387 : | <td valign="Top" width="50%" bgcolor="#c0c0c0"> | ||
| 388 : | |||
| 389 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 390 : | <toc label="PluginB Documentation"></font></div> | ||
| 391 : | |||
| 392 : | |||
| 393 : | <blockquote> | ||
| 394 : | |||
| 395 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 396 : | <topic label="JavaScript" href="js.html"></font></div> | ||
| 397 : | |||
| 398 : | |||
| 399 : | <blockquote> | ||
| 400 : | |||
| 401 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 402 : | <topic label="Netscape" href="ns.html"/></font></div> | ||
| 403 : | |||
| 404 : | |||
| 405 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 406 : | <topic label="IE" href="ie.html"/></font></div> | ||
| 407 : | </blockquote> | ||
| 408 : | |||
| 409 : | |||
| 410 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 411 : | </topic></font></div> | ||
| 412 : | </blockquote> | ||
| 413 : | |||
| 414 : | |||
| 415 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 416 : | </topic></font></div> | ||
| 417 : | </td> | ||
| 418 : | </tr> | ||
| 419 : | |||
| 420 : | |||
| 421 : | </tbody> | ||
| 422 : | |||
| 423 : | </table> | ||
| 424 : | </div> | ||
| 425 : | The doc.zip file in PluginA contains docs/compile.html, docs/java.html | ||
| 426 : | and docs/cpp.html (and any images used). The doc.zip file in PluginB contais | ||
| 427 : | js.html, ns.html and ie.html (and any images used). | ||
| 428 : | |||
| 429 : | <p>Help should display the following table of contents<br> | ||
| 430 : | </p> | ||
| 431 : | |||
| 432 : | |||
| 433 : | <center> | ||
| 434 : | |||
| 435 : | <table border="1" cellpadding="0" width="100%" bgcolor="#c0c0c0"> | ||
| 436 : | <caption><br> | ||
| 437 : | |||
| 438 : | |||
| 439 : | <center></center> | ||
| 440 : | </caption><tbody> | ||
| 441 : | |||
| 442 : | |||
| 443 : | </tbody> <tbody> | ||
| 444 : | <tr> | ||
| 445 : | <td width="808" height="137"><font size="-1"> | ||
| 446 : | Compiling</font> | ||
| 447 : | |||
| 448 : | <p><font size="-1"> | ||
| 449 : | Java files</font> </p> | ||
| 450 : | |||
| 451 : | |||
| 452 : | <blockquote><b><font size="-1">JavaScript</font></b> | ||
| 453 : | |||
| 454 : | |||
| 455 : | <blockquote><b><font size="-1">Netscape</font></b> | ||
| 456 : | |||
| 457 : | |||
| 458 : | <p><b><font size="-1">IE</font></b></p> | ||
| 459 : | </blockquote> | ||
| 460 : | </blockquote> | ||
| 461 : | <font size="-1"> | ||
| 462 : | C++ files</font></td> | ||
| 463 : | </tr> | ||
| 464 : | |||
| 465 : | |||
| 466 : | </tbody> | ||
| 467 : | |||
| 468 : | </table> | ||
| 469 : | </center> | ||
| 470 : | |||
| 471 : | |||
| 472 : | <h4> Scenario 4: basic bottom-up integration</h4> | ||
| 473 : | A typical scenario for a third party ISV is to provide tools (plugins) | ||
| 474 : | and attempt to integrate their documentation with that of the target product | ||
| 475 : | (like IBM's Websphere Studio). For that to happen, the ISV toc file must | ||
| 476 : | link itself to the target toc, and the target doc must expose an anchor for | ||
| 477 : | linking. | ||
| 478 : | |||
| 479 : | <p>The markup for this kind of linking is simply | ||
| 480 : | specifying the link_to attribute on the <toc> element inside the table | ||
| 481 : | of contents file: </p> | ||
| 482 : | |||
| 483 : | |||
| 484 : | <p><toc label="PluginA docs" <b>link_to="../PluginB/toc.xml#anchor_id"</b> | ||
| 485 : | > </p> | ||
| 486 : | |||
| 487 : | |||
| 488 : | <p>The net effect should be the same as if the | ||
| 489 : | target navigation file <link>-ed the ISV navigation component at the | ||
| 490 : | specified anchor. </p> | ||
| 491 : | |||
| 492 : | |||
| 493 : | <p> </p> | ||
| 494 : | |||
| 495 : | |||
| 496 : | <p>Here are the files: </p> | ||
| 497 : | |||
| 498 : | |||
| 499 : | <p>plugin.xml in PluginA and PluginB </p> | ||
| 500 : | |||
| 501 : | |||
| 502 : | <div align="Right"> | ||
| 503 : | |||
| 504 : | <table border="1" cellpadding="0" width="100%"> | ||
| 505 : | <caption><br> | ||
| 506 : | |||
| 507 : | |||
| 508 : | <div align="Right"></div> | ||
| 509 : | </caption><tbody> | ||
| 510 : | |||
| 511 : | |||
| 512 : | </tbody> <tbody> | ||
| 513 : | <tr> | ||
| 514 : | <td bgcolor="#c0c0c0"> | ||
| 515 : | |||
| 516 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 517 : | <plugin id="PluginA"></font></div> | ||
| 518 : | |||
| 519 : | |||
| 520 : | <blockquote> | ||
| 521 : | |||
| 522 : | |||
| 523 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 524 : | <extension point="org.eclipse.help.toc"></font></div> | ||
| 525 : | |||
| 526 : | |||
| 527 : | <blockquote> | ||
| 528 : | |||
| 529 : | |||
| 530 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 531 : | <toc file="toc.xml"/></font></div> | ||
| 532 : | </blockquote> | ||
| 533 : | |||
| 534 : | |||
| 535 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 536 : | </extension></font></div> | ||
| 537 : | </blockquote> | ||
| 538 : | |||
| 539 : | |||
| 540 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 541 : | </plugin></font></div> | ||
| 542 : | </td> | ||
| 543 : | <td bgcolor="#c0c0c0"> | ||
| 544 : | |||
| 545 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 546 : | <plugin id="PluginB"></font></div> | ||
| 547 : | |||
| 548 : | |||
| 549 : | <blockquote> | ||
| 550 : | |||
| 551 : | |||
| 552 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 553 : | <extension point="org.eclipse.help.toc"></font></div> | ||
| 554 : | |||
| 555 : | |||
| 556 : | <blockquote> | ||
| 557 : | |||
| 558 : | |||
| 559 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 560 : | <toc file="toc.xml"/></font></div> | ||
| 561 : | </blockquote> | ||
| 562 : | |||
| 563 : | |||
| 564 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 565 : | </extension></font></div> | ||
| 566 : | </blockquote> | ||
| 567 : | |||
| 568 : | |||
| 569 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 570 : | </plugin></font></div> | ||
| 571 : | </td> | ||
| 572 : | </tr> | ||
| 573 : | |||
| 574 : | |||
| 575 : | </tbody> | ||
| 576 : | |||
| 577 : | |||
| 578 : | </table> | ||
| 579 : | </div> | ||
| 580 : | toc.xml in PluginA and PluginB | ||
| 581 : | |||
| 582 : | |||
| 583 : | <div align="Right"><br> | ||
| 584 : | |||
| 585 : | |||
| 586 : | <table border="1" cellpadding="0" width="100%"> | ||
| 587 : | <caption><br> | ||
| 588 : | |||
| 589 : | |||
| 590 : | <div align="Right"></div> | ||
| 591 : | </caption><tbody> | ||
| 592 : | |||
| 593 : | |||
| 594 : | </tbody> <tbody> | ||
| 595 : | <tr> | ||
| 596 : | <td width="50%" bgcolor="#c0c0c0"> | ||
| 597 : | |||
| 598 : | |||
| 599 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 600 : | <toc label=" PluginA Documentation"></font></div> | ||
| 601 : | |||
| 602 : | |||
| 603 : | <blockquote> | ||
| 604 : | |||
| 605 : | |||
| 606 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 607 : | <topic label="Compiling" href="docs/compile.html"></font></div> | ||
| 608 : | |||
| 609 : | |||
| 610 : | <blockquote> | ||
| 611 : | |||
| 612 : | |||
| 613 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 614 : | <topic label="Java files" href="docs/java.html"/></font></div> | ||
| 615 : | |||
| 616 : | |||
| 617 : | <div style="line-height: 100%; "><b><font size="-1"> | ||
| 618 : | <anchor id="other"/></font></b></div> | ||
| 619 : | |||
| 620 : | |||
| 621 : | |||
| 622 : | <p style="line-height: 100%; "><font size="-1"> | ||
| 623 : | <topic label="C++ files" href="docs/cpp.html"/></font></p> | ||
| 624 : | </blockquote> | ||
| 625 : | |||
| 626 : | |||
| 627 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 628 : | </topic></font></div> | ||
| 629 : | </blockquote> | ||
| 630 : | |||
| 631 : | |||
| 632 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 633 : | </topic></font></div> | ||
| 634 : | </td> | ||
| 635 : | <td valign="Top" width="50%" bgcolor="#c0c0c0"> | ||
| 636 : | |||
| 637 : | |||
| 638 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 639 : | <toc label=" PluginB Documentation" <b>link_to="../PluginA/toc.xml#other"</b> | ||
| 640 : | ></font></div> | ||
| 641 : | |||
| 642 : | |||
| 643 : | <blockquote> | ||
| 644 : | |||
| 645 : | |||
| 646 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 647 : | <topic label="JavaScript" href="js.html"></font></div> | ||
| 648 : | |||
| 649 : | |||
| 650 : | |||
| 651 : | <blockquote> | ||
| 652 : | |||
| 653 : | |||
| 654 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 655 : | <topic label="Netscape" href="ns.html"/></font></div> | ||
| 656 : | |||
| 657 : | |||
| 658 : | |||
| 659 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 660 : | <topic label="IE" href="ie.html"/></font></div> | ||
| 661 : | </blockquote> | ||
| 662 : | |||
| 663 : | |||
| 664 : | |||
| 665 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 666 : | </topic></font></div> | ||
| 667 : | </blockquote> | ||
| 668 : | |||
| 669 : | |||
| 670 : | |||
| 671 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 672 : | </topic></font></div> | ||
| 673 : | </td> | ||
| 674 : | </tr> | ||
| 675 : | |||
| 676 : | |||
| 677 : | </tbody> | ||
| 678 : | |||
| 679 : | |||
| 680 : | </table> | ||
| 681 : | </div> | ||
| 682 : | The following table of contents is built: | ||
| 683 : | |||
| 684 : | |||
| 685 : | <center></center> | ||
| 686 : | |||
| 687 : | |||
| 688 : | <table border="1" cellpadding="0" width="100%" bgcolor="#c0c0c0"> | ||
| 689 : | <caption><br> | ||
| 690 : | |||
| 691 : | |||
| 692 : | <center></center> | ||
| 693 : | </caption><tbody> | ||
| 694 : | |||
| 695 : | |||
| 696 : | </tbody><tbody> | ||
| 697 : | <tr> | ||
| 698 : | <td width="808" height="137"><font size="-1"> | ||
| 699 : | <font size="-1">Compiling</font></font> | ||
| 700 : | |||
| 701 : | |||
| 702 : | <p><font size="-1"> | ||
| 703 : | Java files</font></p> | ||
| 704 : | |||
| 705 : | |||
| 706 : | <blockquote><b><font size="-1"> | ||
| 707 : | JavaScript</font></b> | ||
| 708 : | |||
| 709 : | <blockquote><b><font size="-1"> | ||
| 710 : | Netscape</font></b> | ||
| 711 : | |||
| 712 : | <p><b><font size="-1"> | ||
| 713 : | IE</font></b></p> | ||
| 714 : | </blockquote> | ||
| 715 : | </blockquote> | ||
| 716 : | |||
| 717 : | |||
| 718 : | <blockquote><font size="-1"> | ||
| 719 : | C++ files</font></blockquote> | ||
| 720 : | </td> | ||
| 721 : | </tr> | ||
| 722 : | |||
| 723 : | |||
| 724 : | </tbody> | ||
| 725 : | |||
| 726 : | |||
| 727 : | </table> | ||
| 728 : | |||
| 729 : | |||
| 730 : | <h2></h2> | ||
| 731 : | <br> | ||
| 732 : | |||
| 733 : | |||
| 734 : | |||
| 735 : | <h2> REFERENCE</h2> | ||
| 736 : | |||
| 737 : | |||
| 738 : | |||
| 739 : | <h3> Plugin.xml</h3> | ||
| 740 : | A plugin can contribute one or more tables of contents. Tables of contents | ||
| 741 : | files contain navigation info for the help content, i.e.a hierarchical structure | ||
| 742 : | kkolosow | 1.2 | of topic nodes that point to the actual html help documents. By default |
| 743 : | dbirsan | 1.1 | tables of contents are meant to be integrated to other tables of contents. |
| 744 : | Some are considered standalone or master tables of contents, and marked as | ||
| 745 : | primary. Each TOC contributed by a plugin must be defined in the plugin.xml | ||
| 746 : | file under the org.eclipse.help.toc extension point. A plugin can configure | ||
| 747 : | one or more toc extension points, and each toc extension point can define | ||
| 748 : | one or more tables of contents. Multiple TOCs are contributed when needed | ||
| 749 : | to support different navigation views, or to provide reusable table of contents | ||
| 750 : | components. The same TOC should not be defined multiple times. <br> | ||
| 751 : | The DTD for the org.eclipse.help.toc extension point content is as follows: | ||
| 752 : | |||
| 753 : | |||
| 754 : | |||
| 755 : | <p><font size="-1"><!ELEMENT | ||
| 756 : | extension (toc)* ></font> <br> | ||
| 757 : | <font size="-1"><!ATTLIST | ||
| 758 : | extension point CDATA "org.eclipse.help.toc" #FIXED></font> | ||
| 759 : | <br> | ||
| 760 : | <font size="-1"><!--</font> | ||
| 761 : | <br> | ||
| 762 : | <font size="-1">Each | ||
| 763 : | toc extension point can define any number of toc files.</font> <br> | ||
| 764 : | <font size="-1">--></font> | ||
| 765 : | </p> | ||
| 766 : | |||
| 767 : | |||
| 768 : | |||
| 769 : | <p> </p> | ||
| 770 : | |||
| 771 : | |||
| 772 : | |||
| 773 : | <p><font size="-1"><!ELEMENT | ||
| 774 : | toc EMPTY></font> <br> | ||
| 775 : | <font size="-1"><!ATTLIST | ||
| 776 : | toc file CDATA #REQUIRED></font><br> | ||
| 777 : | <font size="-1"><!ATTLIST | ||
| 778 : | toc primary (true | false) "false" ></font><br> | ||
| 779 : | </p> | ||
| 780 : | |||
| 781 : | |||
| 782 : | <p> | ||
| 783 : | <font size="-1"><!--</font> <br> | ||
| 784 : | <font size="-1">Each | ||
| 785 : | toc file definition specifies the toc file by its relative path (href) | ||
| 786 : | to the plugin and whether the plugin contributes it as a section or a table | ||
| 787 : | of contents or as a standalone or master table of contents.</font><br> | ||
| 788 : | <font size="-1">--></font> | ||
| 789 : | <br> | ||
| 790 : | <br> | ||
| 791 : | </p> | ||
| 792 : | |||
| 793 : | |||
| 794 : | |||
| 795 : | <p>Example: <br> | ||
| 796 : | </p> | ||
| 797 : | |||
| 798 : | |||
| 799 : | |||
| 800 : | <blockquote> | ||
| 801 : | |||
| 802 : | |||
| 803 : | |||
| 804 : | <div style="line-height: 100%; "> | ||
| 805 : | <br> | ||
| 806 : | |||
| 807 : | |||
| 808 : | |||
| 809 : | <table border="1" cellspacing="2" cellpadding="2" width="100%"> | ||
| 810 : | <caption><br> | ||
| 811 : | </caption><tbody> | ||
| 812 : | |||
| 813 : | |||
| 814 : | |||
| 815 : | </tbody> <tbody> | ||
| 816 : | <tr> | ||
| 817 : | <td valign="Top" bgcolor="#cccccc"> | ||
| 818 : | |||
| 819 : | |||
| 820 : | <blockquote> | ||
| 821 : | |||
| 822 : | |||
| 823 : | |||
| 824 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 825 : | <extension point="org.eclipse.help.toc<b>"</b>><br> | ||
| 826 : | </font></div> | ||
| 827 : | |||
| 828 : | |||
| 829 : | |||
| 830 : | <blockquote> | ||
| 831 : | |||
| 832 : | |||
| 833 : | |||
| 834 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 835 : | <!-- this defines a standalone table of contents --><br> | ||
| 836 : | <toc file="toc.xml" primary="true"/></font></div> | ||
| 837 : | </blockquote> | ||
| 838 : | |||
| 839 : | |||
| 840 : | |||
| 841 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 842 : | </extension><br> | ||
| 843 : | <br> | ||
| 844 : | </font></div> | ||
| 845 : | |||
| 846 : | |||
| 847 : | |||
| 848 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 849 : | <extension point="<b> org.eclipse.help.toc</b>"></font></div> | ||
| 850 : | |||
| 851 : | |||
| 852 : | |||
| 853 : | <blockquote> | ||
| 854 : | |||
| 855 : | |||
| 856 : | |||
| 857 : | |||
| 858 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 859 : | <!-- this defines two sections --></font><b><font size="-1"><br> | ||
| 860 : | <toc file=</font></b><font size="-1">"tocWSAD.xml"/</font></div> | ||
| 861 : | <br> | ||
| 862 : | <font size="-1"> | ||
| 863 : | <<b>toc href</b>="referencesWSAD.xml" /></font></blockquote> | ||
| 864 : | |||
| 865 : | |||
| 866 : | |||
| 867 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 868 : | </extension></font></div> | ||
| 869 : | |||
| 870 : | |||
| 871 : | |||
| 872 : | <div style="line-height: 100%; "><font size="-1"> | ||
| 873 : | </font></div> | ||
| 874 : | </blockquote> | ||
| 875 : | </td> | ||
| 876 : | </tr> | ||
| 877 : | |||
| 878 : | |||
| 879 : | |||
| 880 : | </tbody> | ||
| 881 : | |||
| 882 : | |||
| 883 : | |||
| 884 : | </table> | ||
| 885 : | </div> | ||
| 886 : | </blockquote> | ||
| 887 : | |||
| 888 : | |||
| 889 : | |||
| 890 : | <h3> Toc.xml</h3> | ||
| 891 : | The new table of contents files combine the 1.0 topics files with the | ||
| 892 : | 1.0 action files in a cleaner document/web centric structure. <br> | ||
| 893 : | In its most basic form, tables of contents are just hierarchical | ||
| 894 : | structures of topics. A topic is really a "pointer" to the actual help file. | ||
| 895 : | Stepping up in complexity, a table of contents can <b>link </b>other | ||
| 896 : | tables of contents when desired, creating larger tables of contents. Conversely, | ||
| 897 : | a table of contents can <b>link to</b> another table of contents, forming | ||
| 898 : | kkolosow | 1.2 | larger navigation tables of contents in a bottom up approach. Linking to |
| 899 : | another table of contents file is done by specifying an anchor in the target table of contents file.<br> | ||
| 900 : | dbirsan | 1.1 | Since topics behave like pointers to a help file, the same html help file |
| 901 : | can be reused in many places, by defining the appropriate topic. Reuse can | ||
| 902 : | kkolosow | 1.2 | also be done in groups of topics, with the table of contents file acting as |
| 903 : | a reusable component.The same table of contents file can be linked many times. | ||
| 904 : | Two branches of the navigation tree will look identical from the reused table | ||
| 905 : | of contents and down. | ||
| 906 : | dbirsan | 1.1 | |
| 907 : | |||
| 908 : | <p>The DTD for the | ||
| 909 : | kkolosow | 1.2 | table of contents file follows: </p> |
| 910 : | dbirsan | 1.1 | |
| 911 : | |||
| 912 : | |||
| 913 : | <p><font size="-1"> | ||
| 914 : | kkolosow | 1.2 | <!ELEMENT toc (topic | anchor | link)* ></font> |
| 915 : | dbirsan | 1.1 | <br> |
| 916 : | <font size="-1"> | ||
| 917 : | kkolosow | 1.2 | <!ATTLIST toc link_to CDATA #IMPLIED></font> |
| 918 : | dbirsan | 1.1 | <br> |
| 919 : | <font size="-1"> | ||
| 920 : | kkolosow | 1.2 | <!ATTLIST toc label CDATA #REQUIRED></font> |
| 921 : | dbirsan | 1.1 | <br> |
| 922 : | <font size="-1"> | ||
| 923 : | <!--</font> <br> | ||
| 924 : | <font size="-1"> | ||
| 925 : | A toc element is the root of the tree of topics defined in the table of | ||
| 926 : | contents file. It can optionally attach to another topics file by providing | ||
| 927 : | its "link_to" attribute. The value of this attribute should be an href to | ||
| 928 : | an anchor defined in this plugin or in another plugin.</font> <br> | ||
| 929 : | <font size="-1"> | ||
| 930 : | Href's to anchors in a table of contents in other plugins | ||
| 931 : | are specified as ../other_plugin_id/path_to_toc_file.xml#anchor_id</font><br> | ||
| 932 : | <font size="-1"> | ||
| 933 : | Each toc element must define a label to be used in its presentation. The | ||
| 934 : | label is only shown when the table of contents is primary and not integrated | ||
| 935 : | into another table of contents (i.e. it is part of the library of the tables | ||
| 936 : | of contents for the product). When linked, the toc element gets bypassed, | ||
| 937 : | kkolosow | 1.2 | and its topics are directly connected to topics at the link point .</font> |
| 938 : | dbirsan | 1.1 | <br> |
| 939 : | <font size="-1"> | ||
| 940 : | A TOC file consist of any number of (nested) topics, anchor | ||
| 941 : | kkolosow | 1.2 | points or links of other TOC files.</font> <br> |
| 942 : | dbirsan | 1.1 | <font size="-1"> |
| 943 : | --></font> </p> | ||
| 944 : | |||
| 945 : | |||
| 946 : | |||
| 947 : | <p><font size="-1"> | ||
| 948 : | <!ELEMENT topic (topic | anchor | link )* ></font> <br> | ||
| 949 : | <font size="-1"> | ||
| 950 : | <!ATTLIST topic label CDATA #REQUIRED></font> | ||
| 951 : | <br> | ||
| 952 : | <font size="-1"> | ||
| 953 : | <!ATTLIST topic href CDATA #IMPLIED></font> | ||
| 954 : | <br> | ||
| 955 : | <font size="-1"> | ||
| 956 : | <!--</font> <br> | ||
| 957 : | <font size="-1"> | ||
| 958 : | kkolosow | 1.2 | Each topic is a node in a table of contents tree and can contain topics, anchor points |
| 959 : | dbirsan | 1.1 | or can include the topics form other tables of contents.</font><br> |
| 960 : | <font size="-1"> | ||
| 961 : | For presentaton purposes, each topic must have a label.</font> <br> | ||
| 962 : | <font size="-1"> | ||
| 963 : | Most topics have a corresponding help content, identified by the href | ||
| 964 : | value. In general the href is a relative path to a file in the same plugin | ||
| 965 : | (in doc.zip or a regular file) or can point to content in another plugin | ||
| 966 : | using the ../another_plugin_id/path_to_content_file.html form.</font> <br> | ||
| 967 : | <font size="-1"> | ||
| 968 : | Topics with no href are there for grouping other topics, for cleaner | ||
| 969 : | tree presentation.</font> <br> | ||
| 970 : | <font size="-1"> | ||
| 971 : | --></font> </p> | ||
| 972 : | |||
| 973 : | |||
| 974 : | |||
| 975 : | <p><font size="-1"> | ||
| 976 : | <!ELEMENT anchor EMPTY></font> <br> | ||
| 977 : | <font size="-1"> | ||
| 978 : | <!ATTLIST anchor id ID #REQUIRED></font> | ||
| 979 : | <br> | ||
| 980 : | <font size="-1"> | ||
| 981 : | <!--</font> <br> | ||
| 982 : | <font size="-1"> | ||
| 983 : | An anchor is really an insertion point for other tables of contents | ||
| 984 : | to link into the structure defined in the current file. If multiple | ||
| 985 : | topics files linked to the same topic, they will be linked in the processing | ||
| 986 : | order. In other words, the order is not guaranteed. Multiple, adjacent anchors | ||
| 987 : | may be used to differentiate among topics that should be linked before or | ||
| 988 : | after the others.</font> <br> | ||
| 989 : | <font size="-1"> | ||
| 990 : | --></font></p> | ||
| 991 : | |||
| 992 : | <p><font size="-1"> | ||
| 993 : | <!ELEMENT link EMPTY></font><br> | ||
| 994 : | <font size="-1"> | ||
| 995 : | <!ATTLIST link toc CDATA #REQUIRED></font><br> | ||
| 996 : | <font size="-1"> | ||
| 997 : | <!--</font><br> | ||
| 998 : | <font size="-1"> | ||
| 999 : | A link is used to link the topics from another table of content</font> | ||
| 1000 : | s.<br> | ||
| 1001 : | <font size="-1"> | ||
| 1002 : | --></font></p> | ||
| 1003 : | |||
| 1004 : | <p><br> | ||
| 1005 : | </p> | ||
| 1006 : | |||
| 1007 : | |||
| 1008 : | |||
| 1009 : | <p><!--ELEMENT include EMPTY--><!--ATTLIST include href CDATA #REQUIRED--><!-- | ||
| 1010 : | An include is the simplest way to extend navigation by integrating other | ||
| 1011 : | topics files available at the place where the element is defined. | ||
| 1012 : | The topic's structure (all topic elements) defined in the file specified by the | ||
| 1013 : | href attribute is inserted into the current file. This includes all the attached or included | ||
| 1014 : | topics files, recursively. | ||
| 1015 : | --> | ||
| 1016 : | </p> | ||
| 1017 : | |||
| 1018 : | |||
| 1019 : | |||
| 1020 : | dbirsan | 1.3 | <h3> Q&A </h3> |
| 1021 : | |||
| 1022 : | <pre> | ||
| 1023 : | (Q) I am curious about the fact that infoviews have gone away. How will | ||
| 1024 : | different views of the infoset work now? | ||
| 1025 : | (A) We need to gather more feedback from the users to understand what is really needed | ||
| 1026 : | to accomplish by using views. This document deals mostly with building TOC's, without | ||
| 1027 : | making too many assumptions about their visual representation in the help view. | ||
| 1028 : | We have been discussing some ways to include/exclude certain TOC's under certain | ||
| 1029 : | conditions, for a role-based presentation of help, but we're still looking for input | ||
| 1030 : | from the users of the technology. | ||
| 1031 : | |||
| 1032 : | (Q) And if infosets are gone, will there be any way of titling a doc web? | ||
| 1033 : | (A) What is the meaning of a doc web? Is it all the docs provided by an eclipse-based | ||
| 1034 : | product? Theoretically, all the plugins contributing | ||
| 1035 : | help are part of a doc web (that of the current eclipse session). If you think that | ||
| 1036 : | you may install two eclipse-based products then what kind of scenario are you looking | ||
| 1037 : | at that you need to differentiate between the two "doc webs"? | ||
| 1038 : | |||
| 1039 : | (Q) I am also a little confused about the statement that properties files, both doc.properties and | ||
| 1040 : | contexts.properties, go away. What are they replaced by? | ||
| 1041 : | (A) The assumption here is that the xml files (toc.xml and context.xml) will be sent to | ||
| 1042 : | translation and packaged in their own fragments just like the translated html content. | ||
| 1043 : | This also allows for having different tables of contents on different languages. The | ||
| 1044 : | drawback is that last minute changes in a TOC will have to be propagated to all | ||
| 1045 : | the translated toc.xml files. | ||
| 1046 : | </pre> | ||
| 1047 : | dbirsan | 1.1 | |
| 1048 : | |||
| 1049 : | |||
| 1050 : | </body> | ||
| 1051 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |