| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <meta name="GENERATOR" content="Mozilla/4.73 [en] (Win98; U) [Netscape]"> |
| <meta name="Author" content="Greg Adams"> |
| <title>Help Part 1</title> |
| <link rel="stylesheet" href="../../default_style.css"> |
| </head> |
| <body> |
| |
| <div align=right><font face="Times New Roman, Times, serif"><font size=-1>Copyright |
| © 2001 Object Technology International, Inc.</font></font></div> |
| <div ALIGN=right><table BORDER=0 CELLSPACING=0 CELLPADDING=2 WIDTH="100%" > |
| <tr> |
| <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF"> Eclipse |
| Corner Article</font></font></b></td> |
| </tr> |
| </table></div> |
| |
| <h1> <img SRC="Idea.jpg" height=86 width=120></h1> |
| |
| <center> |
| <h1> |
| Help Part 1<br> |
| Contributing a little help</h1></center> |
| <b>Summary</b> |
| <br>The Eclipse platforms help system defines two extension points (<tt>"contributions" |
| </tt>and<tt>"contexts"</tt>) |
| that allow individual plug-ins to contribute online help and context-sensitive |
| help for their components. In this article we will investigate the contributions |
| extension point and how you can use it to contribute documentation for |
| your plug-in. |
| <p><b>By Greg Adams, OTI and Dorian Birsan, IBM</b> |
| <br><font size=-1>Updated May 28, 2001</font> |
| <center> |
| <hr size=2 width="100%" align=center></center> |
| |
| <h2> |
| Introduction</h2> |
| The Eclipse platforms help system allows you to contribute your plug-ins online |
| help using the org.eclipse.help.contributions extension point. You can either |
| contribute the online help as part of your code plug-in or provide it separately |
| in its own documentation plug-in. This separation is beneficial in those situations |
| where the code and documentation teams are different groups or where you want |
| to reduce the coupling/dependency between the documentation and code. The platforms |
| help facilities provide you with the raw building blocks to structure and contribute |
| your help. It does not dictate structure or granularity of documentation. The |
| platform does however provide and control the integrated help viewers thus ensuring |
| seamless integration of your documentation. |
| <p>The org.eclipse.help.contributions extension point provides four elements |
| through which you can contribute your help, they are: |
| <ul> |
| <li> |
| topics</li> |
| |
| <li> |
| infoset (also known as a book)</li> |
| |
| <li> |
| infoview</li> |
| |
| <li> |
| actions (also known as wiring)</li> |
| </ul> |
| The topics, infoset and actions contributions all specify an associated |
| xml file that contains the details of the contribution. In the remainder |
| of this article we will create a documentation plug-in that uses all four |
| of these elements. By the time were done, youll have your first online |
| help plug-in. |
| <h2> |
| Making the plug-in and content</h2> |
| A content author supplies one or more HTML files containing the actual |
| documentation. There are no restrictions imposed by the platform on the |
| granularity of the HTML files. That is, the documentation authors can opt |
| to use one massive HTML file, or numerous smaller granularity HTML files. |
| We will start by assuming that you already have some html files that you |
| want to integrate into the Eclipse platform. Lets assume your content |
| is arranged into the following directory tree. |
| <blockquote><tt>doc/</tt> |
| <br><tt> concepts/</tt> |
| <br><tt> concept1.html</tt> |
| <br><tt> concept1_1.html</tt> |
| <br><tt> concept1_2.html</tt> |
| <br><tt> tasks/</tt> |
| <br><tt> task1.html</tt> |
| <br><tt> task2.html</tt> |
| <br><tt> task3_1.html</tt> |
| <br><tt> task3_2.html</tt> |
| <br><tt> ref/</tt> |
| <br><tt> ref1.html</tt> |
| <br><tt> ref2.html</tt></blockquote> |
| Create a plug-in directory called org.eclipse.helparticle and place the above |
| <i>doc\ </i>sub-tree into it<i>. </i>Now create an initial plugin.xml file with |
| the following content: |
| <blockquote><tt><?xml version="1.0"?></tt> |
| <br><tt><plugin</tt> |
| <br><tt> name = "Online Help Sample"</tt> |
| <br><tt> id = "org.eclipse.helparticle"</tt> |
| <br><tt> version = "0.9"</tt> |
| <br><tt> provider-name = "Object Technology International, |
| Inc."></tt> |
| <br><tt></plugin></tt></blockquote> |
| To help you get started here is a zip file containing the above <a href="initialstructure.zip">initial |
| plug-in structure</a>. This plug-in manifest file doesn't actually integrate anything |
| yet but soon we will add our contributions to it. <br> |
| |
| <br> |
| <h2> |
| Topics & HTML Content</h2> |
| Now that we have our sample content files we are ready to create our <b>topics |
| </b>file. |
| A topics file defines the key entry points into the HTML content files |
| by mapping a topic id and label to a reference in one of the HTML files. |
| A topics file acts like a table of contents for a set of html content. |
| Teams migrating onto the Eclipse platform can quickly reuse existing documentation |
| by defining entry points into their existing documentation via the topics |
| file. A plug-in can have one or more topics files. Topics files are sometimes |
| referred to as navigation files since they describe how to navigate the |
| html content. We have three main content areas, concepts, tasks and reference. |
| Our obvious choices are one big topics file, or a topics file for each |
| main content area. Keep in mind this decision is ours to make, and is not |
| a decision the platform dictates to us. If we were really writing our |
| documentation we would have a larger number of files so, with that in mind |
| we will try and keep things manageable by creating a topics file for each |
| of the three content areas as follows: |
| |
| <p class="MsoNormal"><b>topics_Tasks.xml</b> |
| <blockquote><tt><topics id="tasksAll"></tt> |
| <br><tt> <topic id="plainTasks" label="Plain Stuff"></tt> |
| <br><tt> <topic label="Task1" |
| href="doc/tasks/task1.html"/></tt> |
| <br><tt> <topic label="Task2" |
| href="doc/tasks/task2.html"/></tt> |
| <br><tt> </topic></tt> <tt> |
| <topic id="funTasks" label="Fun Stuff" ></tt> |
| <br><tt> <topic label="Task3_1" |
| href="doc/tasks/task3_1.html"/></tt> |
| <br><tt> <topic label="Task3_2" |
| href="doc/tasks/task3_2.html"/></tt> |
| <br><tt> </topic></tt> |
| <br><tt></topics></tt></blockquote> |
| <b>topics_Concepts.xml</b> |
| <blockquote><tt><topics id="conceptsAll"></tt> |
| <br><tt> <topic label="Concept1" href="doc/concepts/concept1.html"></tt> |
| <br><tt> <topic label="Concept1_1" |
| href="doc/concepts/concept1_1.html"/></tt> |
| <br><tt> <topic label="Concept1_2" |
| href="doc/concepts/concept1_2.html"/></tt> |
| <br><tt> </topic></tt> <tt></topics></tt></blockquote> |
| <b>topics_Ref.xml</b> |
| <blockquote><tt><topics id="refAll"></tt> |
| <br><tt> <topic label="Ref1" href="doc/ref/ref1.html"/></tt> |
| <br><tt> <topic label="Ref2" href="doc/ref/ref2.html"/></tt> |
| <br><tt></topics></tt></blockquote> |
| Topics are contributed as part of the <i>topics</i> container element. A <i>topic</i> |
| can be a simple link to content (e.g. Task1) or a hierarchical grouping of sub-topics |
| (e.g. Fun Stuff), or both (e.g. Concept1). When we start wiring these topics into |
| the overall documentation web we will refer to them by their id. When used as |
| a link, the argument to href is assumed to be relative to the current plug-in. |
| Only topics with an id can be manipulated. We can also refer to the id associated |
| with the topics element if we want to refer to all of its enclosed topic entries. |
| Later we will modify the plugin.xml to add the actual contributions pointing to |
| these files. |
| <h2> |
| Creating a book</h2> |
| Now that we have our raw content and topic files its time to create our |
| infoset. An information set (infoset) is a documentation web or book. The |
| Eclipse platform can display any number of infosets. An infoset contains |
| one or more infoviews. An infoview provides a high-level semantic grouping |
| within the infoset. Infoviews could be used to create multiple views onto |
| the document web. For example we could use them to create an integrated |
| view of documentation supplied by many components, or a component based |
| view. We could also use them to create separate views for getting started, |
| tasks and concepts, or as we will shortly do, create one infoview to show |
| them all. The term infoview is used to avoid collision/confusion with the |
| term view in the platforms user interface. Each infoview contains a collection |
| of topics. Sometimes a higher-level component or product team is responsible |
| for weaving together the documentation and topics supplied by a number |
| of its component teams. For our purposes well assume that our plug-in |
| should supply both the topics and the book that integrates the topics. |
| Towards the end of the article we will look at how to make your documentation |
| plug-in live happily in both a component world and a product world. |
| <br> |
| <p>The following infoset has id infoset_SampleGuide and declares one |
| infoview whose id is view_Contents. The id of the infoview will become |
| important as we start wiring in the high level structure for the infoview, |
| and ultimately wiring in the topics we defined earlier. |
| <p><b>infoset_SampleGuide.xml</b> |
| <blockquote><tt><infoset id="infoset_SampleGuide" label="Online Help |
| Sample" href="<b>doc/splash.html</b>"></tt> |
| <br><tt> <<b>infoview</b> label="Content" id="view_Contents" |
| /></tt> |
| <br><tt></infoset></tt></blockquote> |
| Selecting the book called "Online Help Sample" shows one possible infoview |
| called "Content". The following figure shows the eventual look of our help. |
| If multiple infoviews had been declared by our xml file they would show |
| up as additional "infoview tabs" alongside the "Content" tab. Notice that |
| our splash page (contained in splash.html and declared above) is |
| also displayed. |
| <blockquote><img SRC="final.jpg" height=437 width=668></blockquote> |
| |
| <br> |
| <h2> |
| Wiring in the top level structure</h2> |
| Next on our agenda is to define the top-level structure that a user will |
| see within our Contents infoview. We start by creating the following |
| topics file for the top-level topics: |
| <p><b>topics_view_Contents.xml</b> |
| <blockquote><tt><topics id="topics_view_Contents"></tt> |
| <br><tt> <topic id="conceptsRoot" label="Concepts" |
| /></tt> |
| <br><tt> <topic id="tasksRoot" label="Tasks" /></tt> |
| <br><tt> <topic id="funRoot" label="Fun Things" /></tt> |
| <br><tt> <topic id="refRoot" label="Reference" /></tt> |
| <br><tt></topics></tt></blockquote> |
| Now comes the fun part, time to wire in these topics into our Contents |
| infoview. Once weve done that we can then proceed to wire in all of our |
| other topics underneath the above top-level topics. We start by wiring |
| in the top-level topics using the following <b>actions |
| </b>file. |
| <p><b>actions_view_Contents.xml</b> |
| <blockquote><tt><actions infoview="org.eclipse.helparticle.view_Contents"></tt> |
| <br><tt> <insert</tt> |
| <br><tt> from="org.eclipse.helparticle.topics_view_Contents"</tt> |
| <br><tt> to="org.eclipse.helparticle.view_Contents"</tt> |
| <br><tt> as="child"/></tt> |
| <br><tt></actions></tt></blockquote> |
| The following snapshot shows what our infoset (Outline Help Sample) will |
| look like as a result of wiring in these top-level topics. The title (label) |
| of the infoset is only displayed in the combo box if there is more than |
| one infoset. |
| <blockquote> |
| <div align="left"><img SRC="toplevel.jpg" height=99 width=197></div> |
| </blockquote> |
| |
| <h2> |
| Taking a closer look at actions</h2> |
| <div align="left">Before we continue lets take a closer look at the action file |
| and the action elements it contains. The actions file contains scripting actions |
| to be performed on topics and infoviews. Currently there is only one kind of |
| action, the insert action, which is used to wire topics and views together into |
| one integrated information web. The actions are structural actions (insert) |
| and, thus, apply to a certain infoview. So, all the insert actions in an actions |
| file wire their topics into one infoview. If you want to wire into different |
| infoviews, you will need an actions file for each. The insertion points can |
| be topics or infoviews. A topic indicates its willingness to be an insertion |
| point by providing an id. Infoviews are required to have id's. Only fully |
| qualified ids are used as references. For example, the fully qualified topic |
| id of the topic <topic id="conceptsRoot " label="Concepts"> in our |
| org.eclipse.helparticle plug-in is org.eclipse.helparticle.conceptsRoot. In |
| the above actions file we took the topics element with fully qualified id "org.eclipse.helparticle.topics_viewContents" |
| and wired it into the infoview with id "org.eclipse.helparticle.view_Contents". |
| </div> |
| <p>Since the insertion points are sometimes located in other plug-ins, |
| and these plug-ins may not be installed, one can specify an alternate insertion |
| point. By default, if none of the choices succeed, the topic stays under |
| its component hierarchy. The "to" attribute specifies the target insertion |
| point. The topic specified by the "from" attribute is the topic being inserted. |
| Followings are some possible ways to insert a topic and they are specified |
| using the "<b>as</b>" attribute: |
| <ul type=disc> |
| <li> |
| As a child of the insertion point, which is the most common. Attribute: |
| as = "child".</li> |
| |
| <li> |
| As the first child of the insertion point. Attribute as = "first-child".</li> |
| |
| <li> |
| As the last child of the insertion point. Attribute as = "last-child".</li> |
| |
| <li> |
| As the previous sibling of the insertion point (i.e., just before the insertion |
| point at the same level in the navigation tree). Attribute as = "prev-sib".</li> |
| |
| <li> |
| As the next sibling of the insertion point (i.e., just after the insertion |
| point at the same level in the navigation tree). Attribute as = "next-sib".</li> |
| </ul> |
| Alternative insertion options can be provided. The nested insert sub-elements |
| of the insert element provide these alternatives. This can be thought of as a |
| "fall-back" mechanism where if an insert action fails, the nested insert action |
| will be executed. Once the first choice insertion point has been satisfied, the |
| other alternative insertion points are ignored. <br> |
| |
| <h2> |
| Integrating our topics</h2> |
| The time has come to finally integrate our topics into the top-level topics of |
| the Contents infoview. To do this we need another actions file that we will |
| call actions_All.xml (since it integrates all of our topics). |
| <p><b>actions_All.xml</b> |
| <blockquote><tt><actions infoview="org.eclipse.helparticle.view_Contents"></tt> |
| <br><tt> <insert</tt> |
| <br><tt> from="org.eclipse.helparticle.conceptsAll"</tt> |
| <br><tt> to="org.eclipse.helparticle.conceptsRoot"</tt> |
| <br><tt> as="child"/></tt> |
| <br><tt> <insert</tt> |
| <br><tt> from="org.eclipse.helparticle.refAll"</tt> |
| <br><tt> to="org.eclipse.helparticle.refRoot"</tt> |
| <br><tt> as="child"/></tt> |
| <br><tt> <insert</tt> |
| <br><tt> from="org.eclipse.helparticle.plainTasks"</tt> |
| <br><tt> to="org.eclipse.helparticle.tasksRoot"</tt> |
| <br><tt> as="child"/></tt> |
| <br><tt> <insert</tt> |
| <br><tt> from="org.eclipse.helparticle.funTasks"</tt> |
| <br><tt> to="org.eclipse.helparticle.funRoot"</tt> |
| <br><tt> as="child"/></tt> <tt></actions></tt></blockquote> |
| Recall that we had a number of task related html files, and the structure/navigation |
| of these files was defined by topics_tasks.xml as follows: |
| <p><b>topics_Tasks.xml</b> |
| <blockquote><tt><topics id="tasksAll"></tt> |
| <br><tt> <topic id="plainTasks" label="Plain Stuff"></tt> |
| <br><tt> <topic label="Task1" |
| href="doc/tasks/task1.html"/></tt> |
| <br><tt> <topic label="Task2" |
| href="doc/tasks/task2.html"/></tt> |
| <br><tt> </topic></tt> |
| <br><tt> <topic id="funTasks" label="Fun Stuff" ></tt> |
| <br><tt> <topic label="Task3_1" |
| href="doc/tasks/task3_1.html"/></tt> |
| <br><tt> <topic label="Task3_2" |
| href="doc/tasks/task3_2.html"/></tt> |
| <br><tt> </topic></tt> |
| <br><tt></topics></tt></blockquote> |
| In the above actions file we use the insert as child action to take the topic |
| with id org.eclipse.helparticle.plainTasks and insert it and its sub-topics under |
| the topic with id org.eclipse.helparticle.tasksRoot |
| <blockquote><tt><insert</tt> |
| <br><tt> from="org.eclipse.helparticle.plainTasks"</tt> |
| <br><tt> to="org.eclipse.helparticle.tasksRoot"</tt> |
| <br><tt> as="child"/></tt></blockquote> |
| The actions file also takes some of our more entertaining tasks and inserts |
| them into the Fun Things area of the web using the following action. |
| <blockquote><tt><insert</tt> |
| <br><tt> from="org.eclipse.helparticle.funTasks"</tt> |
| <br><tt> to="org.eclipse.helparticle.funRoot"</tt> |
| <br><tt> as="child"/></tt></blockquote> |
| |
| <h2> |
| Finishing our plugin</h2> |
| Before we continue a brief recap is in order: |
| <ul> |
| <li> |
| We started by creating our plug-in and document files.</li> |
| |
| <li> |
| Next we created topic files to describe the structure/navigation of our |
| content.</li> |
| |
| <li> |
| We then moved up one level above content, to the wiring and integration |
| of our book. To do this we created our infoset with its single Contents |
| infoview.</li> |
| |
| <li> |
| Next we created another topics file (topics_view_Contents.xml) to define |
| the top-level topics.</li> |
| |
| <li> |
| Finally we wired it all together using the action files actions_view_Contents.xml |
| (to wire in the top level topics) and actions_All.xml (to wire in the bulk |
| of our topics).</li> |
| </ul> |
| |
| <p><br>The one remaining piece of work is to update our plugin.xml to actually |
| contribute the action, topics, and infoset files that we created. Start |
| with updating the plugin.xml to contribute our infoset: |
| <blockquote><tt><extension point="org.eclipse.help.contributions"></tt> |
| <br><tt> <infoset name="infoset_SampleGuide.xml"/></extension></tt></blockquote> |
| Next we contribute the top-level topics, and the actions file that wires |
| them into our infoset: |
| <blockquote><tt><extension point="org.eclipse.help.contributions"></tt> |
| <br><tt> <topics name="topics_view_Contents.xml"/></tt> |
| <br><tt> <actions name="actions_view_Contents.xml" |
| /></tt> |
| <br><tt></extension></tt></blockquote> |
| Lastly we contribute the bulk of our topics and wire them in: |
| <blockquote><tt><extension point="org.eclipse.help.contributions"></tt> |
| <br><tt> <topics name="topics_Concepts.xml" /></tt> |
| <br><tt> <topics name="topics_Tasks.xml" /></tt> |
| <br><tt> <topics name="topics_Ref.xml" /></tt> |
| <br><tt> <actions name="actions_All.xml" /></tt> |
| <br><tt></extension></tt></blockquote> |
| Thats it, youre done. Now take your plugin (click here for a <a href="final.zip">zip |
| file</a> of the final plugin) and drop it into the platforms <i>plugins</i> directory, |
| start eclipse and choose Help -> Help Contents. Once you expand the topics in |
| the Contents infoview you will see the following. <br> |
| |
| <p><img SRC="final.jpg" height=437 width=668> <br> |
| |
| <br> |
| <h2> |
| Non-integrated components</h2> |
| What if we expect our plug-in will sometimes be installed by itself, and in other |
| cases it will be installed as part of a larger component or product. When deploying |
| a free floating plug-in we want to ensure that our infoset is visible. When topics |
| from a plug-in are integrated into a larger web it probably doesnt make sense |
| for their standalone book to show up anymore. To support this nonintegrated or |
| loosely integrated documentation, a plug-in can define an infoset and associated |
| actions and set their <b>standalone</b> attribute to true. This has the effect |
| of executing the inserts only when those topics have never been contributed anywhere |
| else and only display the infoset if it is not empty. In other words, this behaves |
| as: "if this is an independent plug-in, and there are no topics contributed to |
| some well-known infoset, then insert the documentation into a standalone info |
| set". Empty standalone infosets are not shown. This really says that if the topics |
| contributed by the plug-in are inserted into well-known infosets, then the standalone |
| actions did not insert anything in the standalone infoset, so just ignore this |
| empty infoset. Setting standalone attributes on actions and infosets is useful |
| when providing a "Catch all" scenario, when documentation cannot be contributed |
| to a well-known infoset but the plug-in documentation should still appear somewhere. |
| To support standalone mode we need to make the following additions to our infoset |
| and action xml files. The addition is marked in bold. |
| <p>infoset_Guide.xml |
| <br><tt> <infoset id="infoset_Guide"label="Online |
| Help Sample" href="doc/splash.html" |
| <b>standalone="true"</b>></tt> |
| <p>actions_All.xml |
| <br><tt> <actions infoview="org.eclipse.platform.doc.user.view_Contents" |
| <b>standalone="true"</b>></tt> |
| <p>actions_view_Contents.xml |
| <br><tt> <actions infoview="org.eclipse.platform.doc.user.view_Contents" |
| <b>standalone="true"</b>></tt> |
| <p>Now if someone includes our topics our actions will not be used, and |
| consequently our infoset will be empty and not show up. |
| <br> |
| <h2> Externalizing Strings in your XML files</h2> |
| Plugin.xml files externalize their strings by replacing the string with |
| a key (e.g. %pluginName) and creating an entry in the plugin.properties |
| file of the form: |
| <br><tt> pluginName = Online Help Sample Plugin</tt> |
| <br>The contribution XML files are externalized using a similar approach. |
| To externalize <topic id="plainTasks" label="Plain Stuff"> we replace |
| its label with a key %plainStuff . Our topic now looks like: |
| <br><tt> <topic id="plainTasks" label="%plainStuff"></tt> |
| <br>Create an entry in the document.properties file containing the entry: |
| <br><tt> plainStuff = Plain Stuff</tt> |
| <br>The help system will use document.properties when looking up strings |
| externalized by our online help contributions. |
| <br> |
| <h2> |
| Server and zip files</h2> |
| The platform utilizes its own documentation server to provide the actual web pages |
| from within the document web. A custom server allows the platform to handle |
| the wide variety of web browsers in a browser independent way while also providing |
| plugin aware support. The platform's help server allows the documentation to also |
| be deliver in a zip file thus avoiding problems that may result when a large number |
| of files are present. In our example plugin we created a sub-directory called |
| "doc". Alternatively we could have placed our html files into a zip file called |
| "doc.zip". <br> |
| |
| <h2> |
| Conclusions</h2> |
| We have seen how we can use the infoset, infoview to declare books the |
| user can see. We then used the actions contribution and the topics contribution |
| to declare and integrate our topics. The platforms mechanisms can be used |
| to integrate new documentation, or to quickly wire in existing html based |
| documentation without rewriting it. The mechanisms allow you to create |
| multiple different views onto your documentation web. In our plug-in we |
| only created a single infoview but additional infoviews could easily be |
| created. Component documentation can either be written to be a standalone |
| book, or optionally marked such that if it is integrated into a larger |
| document web, the individual component book will automatically be hidden. |
| Lastly, we observed that the platform provides the building blocks for |
| doc integration but does not set out any style or structuring guidelines. |
| <br> |
| <br> |
| </body> |
| </html> |
