| <!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.51 [en] (WinNT; U) [Netscape]"> | |
| <title>Help System extension points: Contributions</title> | |
| </head> | |
| <body link="#0000FF" vlink="#800080"> | |
| <center> | |
| <h1> | |
| Contributions</h1></center> | |
| <b><i>Identifier: </i></b>org.eclipse.help.contributions | |
| <p><b><i>Description:</i></b> For registering an online help contribution | |
| for an individual plug-in. | |
| <p>Each plug-in that contributes help files should in general do the following: | |
| <ul> | |
| <ul> | |
| <li> | |
| author the html files and store them in the plug-in directory (perhaps | |
| using a subdirectory, for cleaner structure).</li> | |
| <li> | |
| create navigation manifest files that describe navigation (table of contents) | |
| for the help and the necessary topic interleaving. See the syntax below.</li> | |
| <li> | |
| the plugin.xml file should extend the <tt>org.eclipse.help.contributions</tt> | |
| extension point and specify the navigation file(s).</li> | |
| </ul> | |
| </ul> | |
| <b><i>Configuration Markup for the <tt>contributions</tt> extension point:</i></b> | |
| <p><tt> <!ELEMENT topics EMPTY></tt> | |
| <br><tt> <!ATTLIST topics name CDATA #REQUIRED></tt> | |
| <ul> | |
| <li> | |
| <b>name<i> </i></b>- the name of the manifest file which contains the table | |
| of contents/navigation for this plug-in's online help.</li> | |
| </ul> | |
| <tt> <!ELEMENT actions EMPTY></tt> | |
| <br><tt> <!ATTLIST actions name CDATA #REQUIRED></tt> | |
| <ul> | |
| <li> | |
| <b>name<i> </i></b>- the name of the manifest file which contains the insertion | |
| rules for topic interleaving and wiring of topics to views<b><i>.</i></b></li> | |
| </ul> | |
| <tt> <!ELEMENT infoset EMPTY></tt> | |
| <br><tt> <!ATTLIST infoset name CDATA #REQUIRED></tt> | |
| <ul> | |
| <li> | |
| <b>name</b> - the name of the manifest file defining the views.</li> | |
| </ul> | |
| <i><b>Configuration Markup for Topics </b>(this is what goes into the topics | |
| manifest file)<b>:</b></i> | |
| <p><tt> <!ELEMENT topics (topic)* ) ></tt> | |
| <br><tt> <!ATTLIST topics id ID #REQUIRED ></tt> | |
| <p><tt> <!ELEMENT topic (topic)* ></tt> | |
| <br><tt> <!ATTLIST topic id ID #IMPLIED ></tt> | |
| <br><tt> <!ATTLIST topic label CDATA #REQUIRED ></tt> | |
| <br><tt> <!ATTLIST topic href CDATA #IMPLIED | |
| ></tt> | |
| <br><tt> <font color="#000000"><!ATTLIST topic insert-constraint | |
| (child | first-child | last-child | prev-sib | next-sib) "child"></font></tt> | |
| <p><i><b>Configuration Markup for Infosets </b>(this is what goes into | |
| the infoset manifest file)<b>:</b></i> | |
| <p><tt> <!ELEMENT infoset (infoview)* ></tt> | |
| <br><tt> <!ATTLIST infoset id ID | |
| #REQUIRED ></tt> | |
| <br><tt> <!ATTLIST infoset label CDATA | |
| #REQUIRED ></tt> | |
| <br><tt> <!ATTLIST infoset standalone | |
| (false|true) false #IMPLIED ></tt> | |
| <p><tt> <!ELEMENT infoview EMPTY></tt> | |
| <br><tt> <!ATTLIST infoview id ID #REQUIRED ></tt> | |
| <br><tt> <!ATTLIST infoview label CDATA #IMPLIED ></tt> | |
| <p><i><b>Configuration Markup for Insert Actions </b>(this is what goes | |
| into the actions manifest file)<b>:</b></i> | |
| <p> <tt> <!ELEMENT actions (insert)* ></tt> | |
| <br><tt> <!ATTLIST actions infoview CDATA #REQUIRED | |
| ></tt> | |
| <br><tt> <!ATTLIST actions standalone (true | false) | |
| false #IMPLIED ></tt> | |
| <p><tt> <!ELEMENT insert (insert) ></tt> | |
| <br><tt> <!ATTLIST insert from CDATA #REQUIRED ></tt> | |
| <br><tt> <!ATTLIST insert to CDATA #REQUIRED ></tt> | |
| <br><tt> <!ATTLIST insert as <font color="#000000">(child | |
| | first-child | last-child | prev-sib | next-sib) "child" ></font></tt> | |
| <br><tt> <!ATTLIST insert label CDATA #IMPLIED ></tt> | |
| <p>In general, a plug-in that needs to provide online help will define | |
| its own topics manifests and the necessary actions manifests to wire the | |
| topics to the correct place. In the end, the help system is configured | |
| to be launched as some actions, and the id of the views manifest will be | |
| used to do so. | |
| <p>There are four types of XML elements a plug-in can use: the topic, the | |
| infoset, the actions, and the insert elements. | |
| <p><b>The topic element</b> | |
| <p>With respect to topics elements, all the topics are contributed as part | |
| of the topics container element. They can have a hierarchical structure, | |
| or can be listed as a flat list. A topics manifest is viewed as a data | |
| source for further topics interleaving and organization into an integrated | |
| web, with different view perspectives. In addition, topics can be | |
| acted upon by specifying their id's, but one can also act on a group of | |
| topics by specifying the id of the topics element that contains them. | |
| Later when wiring topics to views or other topics, the structure defined | |
| in the topics manifest is maintained (subject to alterations done by insert | |
| actions). | |
| <p>The topic element is the workhorse of the navigation structure. There | |
| are three typical uses for the topic element: | |
| <p>1. To provide a link to a documentation file - often an HTML file | |
| in some doc.zip. | |
| <br>2. To act as a container for other topics, either in the same | |
| manifest or another. | |
| <br>3. To provide an insertion point for other topics, either in | |
| the same manifest or another. | |
| <p><b><i>1. Topics as links</i></b> | |
| <br>The simplest use of a topic is as a link to a documentation file. | |
| <p><tt><topic label="Some concept file" href="concepts/some_file.html" | |
| /></tt> | |
| <p>The href attribute is relative to the plug-in that the manifest file | |
| belongs to. If you need to access a file in another plug-in, you | |
| can use the syntax | |
| <p><tt><topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" | |
| /></tt> | |
| <p><b><i>2. Topics as containers</i></b> | |
| <br>The next most common use of a topic is to use it as a container for | |
| other topics. The container topic itself can always refer to a particular | |
| file as well. | |
| <p><tt><topic label="Integrated Development Environment" href="concepts/ciover.htm" | |
| ></tt> | |
| <br><tt> <topic label="Starting the IDE" href="concepts/blah.htm" | |
| /></tt> | |
| <br><tt> ...</tt> | |
| <br><tt></topic></tt> | |
| <p>If you leave the label off the topic, it acts as a "pure" container, | |
| used either as an anchor for other topics to insert around, or to simplify | |
| inserting a group of topics into a specific point in the merged navigation. | |
| <p><b><i>3. Topics as insertion points</i></b> | |
| <br>Topics can be used as insertion points. They provide a logical | |
| place for other topics to try and merge around. To act as an insertion | |
| point, the topic must have an id attribute. | |
| <p><b>The infoset element</b> | |
| <p><font color="#000000">An information set is an entry point into a documentation | |
| web: a collection of all the online documentation that can be displayed | |
| by the help viewer when launched. It can be thought of as a collection | |
| of views.</font> | |
| <p><font color="#000000">Views are intended to provide high level semantic | |
| groupings within a documentation web. They are defined using the </font><tt>infoview | |
| </tt><font color="#000000">element | |
| defined within an infoset. A documentation team could use a view to produce | |
| getting started, tasks, and references sections (or other views the product | |
| team defines). The platform does not specify the actual sections, only | |
| the mechanism for defining them.</font> | |
| <p><font color="#000000">For example, there can be a "task view" defined | |
| which is a merge of all the topics from a "how to do something" perspective. | |
| Another view, a "component view", can also be defined which is a topics | |
| tree displaying all components and their documentation. In the current | |
| implementation of the help system a "search view" is always added to the | |
| list of views. This view enables the user to access help topics by querying | |
| for a word/phrase.</font> | |
| <p>The infoview element represents a container for topics that can be "shared" | |
| across plug-ins. It is a perspective on the entire documentation. | |
| There may be times when a number of different plug-ins contribute to the | |
| same logical documentation component. This element ensures that during | |
| a "component view," they are correctly merged together into a coherent | |
| view. | |
| <p><b>The actions element</b> | |
| <p>The actions manifest contains scripting actions to be performed on topics | |
| and views. Currently there is only one kind of action, the insert action, | |
| which is used to write topics and views together into one integrated information | |
| web, with multiple views. | |
| <p>The actions are structural actions (insert) and, thus, apply to a certain | |
| infoview. So, all the insert actions in a manifest build the topic hierarchy | |
| in one infoview. | |
| <p><b>The insert element</b> | |
| <p>One of the most complicated parts of a componentized navigation is how | |
| to create an integrated information structure with a continuous flow of | |
| navigation. To do this, we need a mechanism to publish insertion | |
| points, choose which insertion point we want to use, and to indicate where | |
| we want to insert topics (parent, child, before, after). | |
| <p>The insertion points can be topics or views. A topic indicates | |
| its willingness to be an insertion point by providing an id. Views are | |
| required to have id's. Only fully qualified ids are use as references. | |
| <font color="#000000">For | |
| example, the fully qualified topic id of the topic <topic id="concepts" | |
| label="Concepts"> in the org.eclipse.help.examples.ex1 | |
| </font>plug-in<font color="#000000"> | |
| is org.eclipse.help.examples.ex1.concepts.</font> | |
| <p>Since the insertion points are typically located in other plug-ins, | |
| and these plug-in 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 as attribute: | |
| <ul> | |
| <li> | |
| As a child of the insertion point, which is the most common.</li> | |
| <li> | |
| As the first child of the insertion point</li> | |
| <li> | |
| As the last child of the insertion point</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)</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)</li> | |
| </ul> | |
| Alternative insertion options are provided, when previous ones could not | |
| be performed. The nested insert subelements 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> | |
| <p><b><i>Examples:</i></b> | |
| <p>The following is an example of using the <tt>contributions</tt> extension | |
| point. Assume the following is for a plug-in with id named <tt>"com.example.isvguide"</tt>. | |
| (The example is intended as a general sample, and it should be noted that | |
| the same documentation hierarchy, resulting from all the following contribution | |
| files, could also be created with various combination of topics and actions | |
| files.) | |
| <p>(in file <tt>plugin.xml</tt>) | |
| <br> | |
| <p><tt> <!-- Use the Help System contribution extension | |
| point to define Infosets, topics, --></tt> | |
| <br><tt> <!-- and actions contribution files. For clarity, | |
| the extension point is used --></tt> | |
| <br><tt> <!-- twice, once to define the Infoset and it's | |
| view, and another to define the --></tt> | |
| <br><tt> <!-- Topics and their associated actions. | |
| --></tt> | |
| <br><tt> <extension point="org.eclipse.help.contributions"></tt> | |
| <br><tt> <infoset name="infoset.xml"/></tt> | |
| <br><tt> </extension></tt> | |
| <p><tt> <extension point="org.eclipse.help.contributions"></tt> | |
| <br><tt> <actions name="infosetActions.xml"/></tt> | |
| <br> <tt><topics | |
| name="infosetTopics.xml"/></tt> | |
| <br><tt> <topics name="concepts.xml"/></tt> | |
| <br><tt> <topics name="tasks.xml"/></tt> | |
| <br><tt> <topics name="reference.xml"/></tt> | |
| <br><tt> <topics name="samples.xml"/></tt> | |
| <br><tt> <topics name="pdfdocuments.xml"/></tt> | |
| <br><tt> </extension></tt> | |
| <br> | |
| <p>(in file <tt>infoset.xml</tt>) | |
| <blockquote><tt><!-- Define the Infoset, and any views it has. --></tt> | |
| <br><tt><infoset id="someinfosetid" label="Plug-In Development" href="isv_home.html"></tt> | |
| <br><tt> <infoview id="topicsView" label="Topics"/></tt> | |
| <br><tt></infoset></tt></blockquote> | |
| <p><br>(in file <tt>infosetTopics.xml</tt>) | |
| <blockquote><tt><!-- Now define a "container" topic that holds your | |
| general topics. This makes it --></tt> | |
| <br><tt><!-- easier to quickly insert all these general topics under | |
| the view in the --></tt> | |
| <br><tt><!-- Infoset. | |
| --></tt> | |
| <br><tt><topics id="topLevelTopics"></tt> | |
| <br><tt> <topic id="concepts" label="Basic Concepts"/></tt> | |
| <br><tt> <topic id="tasks" label="Tasks"/></tt> | |
| <br><tt> <topic id="reference" label="Reference Information"/></tt> | |
| <br><tt> <topic id="samples" label="Samples"/></tt> | |
| <br><tt> <topic id="pdfdocs" label="PDF Documents"/></tt> | |
| <br><tt></topics></tt></blockquote> | |
| <p><br>Define topics contained in the above general topics: | |
| <p>(in file <tt>concepts.xml</tt>) | |
| <blockquote><tt><topics id="Concepts_topics"></tt> | |
| <br><tt> <topic id="aConceptId" label="Introduction" href="concepts/intro.html"/></tt> | |
| <br><tt></topics></tt></blockquote> | |
| <p><br>(in file <tt>tasks.xml</tt>) | |
| <blockquote><tt><topics id="Tasks_topics"></tt> | |
| <br><tt> <topic id="aTaskId" label="Creating a Project" href="tasks/createProject.html"/></tt> | |
| <br><tt></topics></tt></blockquote> | |
| <p><br>(in file <tt>reference.xml</tt>) | |
| <blockquote><tt><topics id="Reference_topics"></tt> | |
| <br><tt> <topic id="aReferenceId" label="Interfaces" href="ref/index.html"/></tt> | |
| <br><tt></topics></tt></blockquote> | |
| <p><br>(in file <tt>samples.xml</tt>) | |
| <blockquote><tt><topics id="Samples_topics"></tt> | |
| <br><tt> <topic id="aSampleId" label="Help System Sample" href="samples/helpSample1.html"/></tt> | |
| <br><tt></topics></tt></blockquote> | |
| <p><br>(in file <tt>pdfdocuments.xml</tt>) | |
| <blockquote><tt><topics id="PDFDocument_topics"></tt> | |
| <br><tt> <topic id="aPDFDocumentId" label="Plug-in development" | |
| href="pdf/isvdoc.pdf"/></tt> | |
| <br><tt></topics></tt></blockquote> | |
| <p><br>Now define the insert actions necessary to create the documentation | |
| hierarchy : | |
| <p>(in file <tt>infosetActions.xml</tt>) | |
| <blockquote><tt><actions infoview="com.example.isvguide.topicsView"></tt> | |
| <p><tt> <insert from="com.example.isvguide.topLevelTopics" | |
| to="com.example.isvguide.topicsView" as="child"/></tt> | |
| <p><tt> <insert from="com.example.isvguide.Concepts_topics"</tt> | |
| <br><tt>to="com.example.isvguide.concepts" as="child"/></tt> | |
| <p><tt> <insert from="com.example.isvguide.Tasks_topics"</tt> | |
| <br><tt>to="com.example.isvguide.tasks" as="child"/></tt> | |
| <p><tt> <insert from="com.example.isvguide.Reference_topics"</tt> | |
| <br><tt>to="com.example.isvguide.reference" as="child"/></tt> | |
| <p><tt> <insert from="com.example.isvguide.Samples_topics"</tt> | |
| <br><tt>to="com.example.isvguide.samples" as="child"/></tt> | |
| <p><tt> <insert from="com.example.isvguide.PDFDocument_topics"</tt> | |
| <br><tt>to="com.example.isvguide.pdfdocs" as="child"/></tt> | |
| <br><tt></actions></tt></blockquote> | |
| <p><br>Here is the resulting documentation hierarchy in the Eclipse Workbench | |
| : | |
| <p><img SRC="HelpSample.JPG" height=497 width=674> | |
| <blockquote> </blockquote> | |
| <blockquote> </blockquote> | |
| <h4> | |
| Non-integrated components</h4> | |
| There is a variation in the default handling of contributions to allow | |
| for "non-integrated" components. Here is a simple scenario: an ISV creates | |
| a component that includes some documentation. The component can be installed | |
| by anybody using eclipse, including some larger products that have their | |
| own infosets. The ISV may or may not know in advance who are the potential | |
| users of his component. In that case, he wants to ensure that the documentation | |
| for the component can be accessed, no matter how the component is integrated. | |
| If there are well-known infosets in some products, the ISV can target its | |
| documentation for wiring into those infosets. In that case the default | |
| infoset provided by the component should not be shown. If there are no | |
| well-known infosets that the component can be wired into (because they | |
| have not been installed or they simply do not exist), then the component | |
| documentation should be shown in the default infoset provided with the | |
| component. | |
| <p>To support this non-integrated or loosely integrated documentation, | |
| a plugin can define an infoset and associated actions and set their <b>standalone</b> | |
| attribute to false. 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 plugin, 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 plugin are inserted into well known infosets, then the | |
| standalone actions did not insert anything in the standalone infoset, so | |
| just ignore this empty infoset. | |
| <br>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 plugin documentation should still appear | |
| somewhere. | |
| <br> | |
| <p><b><i>API Information</i>:<font color="#CC0000"> </font></b>No code | |
| is required to use this extension point. All that is needed is to supply | |
| the appropriate manifest files mentioned in the <tt>plugin.xml</tt> file. | |
| <p><i><b>Supplied Implementation:</b> </i>The optional default implementation | |
| of the help system UI supplied with the Eclipse platform fully supports | |
| the <tt>contributions</tt> extension point. | |
| <p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corporation 2000" BORDER=0 height=12 width=195></a> | |
| </body> | |
| </html> |