platform-help-home/online_help2.0.html
Parent Directory
| 
Revision Log
Revision 1.2 -
(download)
(as text)
(annotate)
Tue Nov 13 01:00:30 2001 UTC (8 years ago) by kkolosow
Branch: MAIN
Changes since 1.1: +14 -14 lines
Tue Nov 13 01:00:30 2001 UTC (8 years ago) by kkolosow
Branch: MAIN
Changes since 1.1: +14 -14 lines
correcting minor inconsistencies
<!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 http-equiv="Content-Language" content="en-us">
<title>Eclipse online help 2.0 changes</title>
</head>
<body>
<h1> ONLINE HELP CHANGES</h1>
<i>(First draft: Nov 13, 2001</i>)<br>
<br>
Early adopters of the eclipse help system version 1.0 have provided considerable
feedback on the contribution mechanism for online help and there seems
to be a consensus on the following as direction for further work:
<ul>
<li> documentation pluggability is great, don't drop this feature</li>
<li> need a simpler mechanism to plug-in the documentation</li>
</ul>
As such, the proposed changes are meant to simplify the help contributions
mechanism, to allow for simple migration from R1.0 and not to introduce
radically new concepts.<br>
<br>
<h2>CONCEPTS<br>
</h2>
This section describes in very general terms the basics of the eclipse
online documentation.<br>
<br>
Eclipse-based products are made up of a number of plugins, each plugin contributing
some function, and/or documentation. Documentation consists of two parts:
the actual html help files and the corresponding table of contents (TOC). Documentation
is, thus, distributed across plugins and comes together as an integrated documentation
library at runtime. Tables of contents across all plugins are usually integrated
by linking them to one another to form larger, more product centric view
of the documentation. Most often a plugin defines a primary table of contents
to which other plugins integrate their own table of contents contributions.
<br>
Tables of contents are really the unit of work, the building blocks of the
documentation navigation. Tables of contents can link any other table of contents,
and can be linked to any other table of contents that allows linking. After
all the table of contents linking has been performed some tables of contents
are said to be integrated and some not. Those that are not integrated are
discarded and the library only contains the integrated tables of contents.
<br>
<br>
A table of contents is considered to be integrated if:<br>
<ul>
<li>it is primary</li>
<li>it is linked to an integrated table of contents<br>
</li>
</ul>
A plugin indicates its desired integration of a table of contents by tagging
it as "primary" or not:<br>
<ul>
<li>a table of contents is not tagged as primary when it is meant to be
integrated into another table of contents</li>
<li>a table of contents should be tagged as primary when it is complete
by itself and is not related to other table of contents, or when it is meant
to be the master toc, the skeleton to which other toc's will integrate<br>
</li>
</ul>
Clearly, a primary table of contents can link to other (primary or
not) tables of contents and can link other tables of contents to it. So, tagging
a TOC primary or not only declares an integration intention, not the final
outcome.<br>
<br>
Finally, the set of tables of contents forming the documentation library
is the set of all primary tables of contents that are not linked to another
integrated table of contents. In general it is the set of all the primary
tables of contents, but sometimes, when some primary table of contents is
linked (directly or indirectly) into another primary table of contents then
it is no longer presented as a top level TOC.<br>
<br>
<h2>CHANGES</h2>
<p>At a glance, here are the main changes: </p>
<ul>
<li> Removed</li>
<ul>
<li> information sets (infosets)</li>
<li> information views (infoviews)</li>
<li> actions</li>
<li> topic ids's</li>
<li> properties files: doc.properties and context.properties</li>
</ul>
<li> Unchanged:</li>
<ul>
<li> html help content still goes into doc.zip or unpacked in the plugin
dir</li>
<li> pluggability (i.e. documentation and navigation can stay in the same
plugins): plugins contribute documentation and corresponding navigation structure(s),
that will be merged at runtime into an eclipse-wide documentation.</li>
</ul>
<li> Slightly changed</li>
<ul>
<li> topics.xml files are now toc.xml files</li>
<li> the extension point for contributing help</li>
</ul>
<li> New</li>
<ul>
<li>document/web centric approach to building tables of contents using
linking of smaller, distributed tables of contents</li>
<li> href/URL based mechanism for naming any help resource, including
navigation</li>
</ul>
</ul>
The above suggests that migrating from version 1.0 should be straightforward,
as the html help content (doc.zip) does not change, the topics.xml files
are also almost identical and the modularization of documentation across
plugins can stay the same. There will be a separate document describing migration
steps, tips, and examples.
<p> <br>
</p>
<h2> SCENARIOS</h2>
It helps to look at a few scenarios to understand how help contributions
work.
<h4> Scenario 1: very basic</h4>
The simplest case is when there is exactly one documentation plugin that
consists of a doc.zip and the associated table of contents. The table of
contents should be declared primary, as it makes sense to be standalone.
<p>Here are the files: </p>
<p>plugin.xml </p>
<div align="Right">
<table border="1" cellpadding="0" width="100%">
<caption><br>
<div align="Right"></div>
</caption><tbody>
</tbody> <tbody>
<tr>
<td width="100%" bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1"><plugin id="MyPlugin"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1"><extension point="org.eclipse.help.toc"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1"><toc file="toc.xml"
primary="<b>true</b>" /></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1"></extension></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1"></plugin></font></div>
</td>
</tr>
</tbody>
</table>
</div>
toc.xml
<div align="Right">
<table border="1" cellpadding="0" width="100%">
<caption><br>
<div align="Right"></div>
</caption><tbody>
</tbody> <tbody>
<tr>
<td width="100%" bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1"><toc label="My
Plugin Documentation"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1"><topic label="Compiling"
href="docs/compile.html"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1"><topic label="Java
files" href="docs/java.html"/.></font></div>
<div style="line-height: 100%; "><font size="-1"><topic label="C++
files" href="docs/cpp.html"/></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1"></topic></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1"></toc></font></div>
</td>
</tr>
</tbody>
</table>
</div>
The doc.zip file contains docs/compile.html, docs/java.html and docs/cpp.html
(and any images used).
<p>The Help library consists of the following navigation structure</p>
<center>
<table border="1" cellpadding="0" width="100%" bgcolor="#c0c0c0">
<caption><br>
<center></center>
</caption><tbody>
</tbody> <tbody>
<tr>
<td width="808" height="137"><font size="-1">
Compiling</font>
<p><font size="-1">
Java files</font> </p>
<p><font size="-1">
C++ files</font></p>
</td>
</tr>
</tbody>
</table>
</center>
<h4> Scenario 2: basic</h4>
There are a few documentation plugins, none being aware of the others
existence (i.e. TOC's are standalone). In this case, each table of contents
is tagged as a "primary" and the library consists of the collection of all
the defined TOC's.
<h4> Scenario 3: top-down integration</h4>
A common scenario is to build an eclipse-based product and have the navigation
distributed in a number of plugins, with a master plugin providing the
navigation skeleton. The master table of contents file would then
include the other tables of contents at certain point and is marked as primary.
<p>The basic markup is to add an <<b>link toc="../another_pluginID/another_toc_section.xml"></b>
at the desired point in a table of contents. This basically links (integrates)
the "another_toc.xml" navigation. The effect of this is that the help system
now has just one big table of contents that is made up of smaller ones. </p>
<p>Here are the files: </p>
<p>plugin.xml in PluginA and PluginB </p>
<div align="Right">
<table border="1" cellpadding="0" width="100%">
<caption><br>
<div align="Right"></div>
</caption><tbody>
</tbody> <tbody>
<tr>
<td bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1"><plugin
id="PluginA"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1"><extension
point="org.eclipse.help.toc"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1"><toc
file="toc.xml" type="<b>toc</b>"/></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1"></extension></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1"></plugin></font></div>
</td>
<td bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1"><plugin
id="PluginB"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1"><extension
point="org.eclipse.help.toc"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1"><toc
file="toc.xml"/></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1"></extension></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1"></plugin></font></div>
</td>
</tr>
</tbody>
</table>
</div>
toc.xml in PluginA and PluginB
<div align="Right"><br>
<table border="1" cellpadding="0" width="100%">
<caption><br>
<div align="Right"></div>
</caption><tbody>
</tbody> <tbody>
<tr>
<td width="50%" bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1"><toc
label="PluginA Documentation"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<topic label="Compiling" href="docs/compile.html"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<topic label="Java files" href="docs/java.html"/></font></div>
<div style="line-height: 100%; "><b><font size="-1">
<link toc="../PluginB/toc.xml"/></font></b></div>
<p style="line-height: 100%; "><font size="-1">
<topic label="C++ files" href="docs/cpp.html"/></font></p>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</topic></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</topic></font></div>
</td>
<td valign="Top" width="50%" bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1">
<toc label="PluginB Documentation"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<topic label="JavaScript" href="js.html"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<topic label="Netscape" href="ns.html"/></font></div>
<div style="line-height: 100%; "><font size="-1">
<topic label="IE" href="ie.html"/></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</topic></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</topic></font></div>
</td>
</tr>
</tbody>
</table>
</div>
The doc.zip file in PluginA contains docs/compile.html, docs/java.html
and docs/cpp.html (and any images used). The doc.zip file in PluginB contais
js.html, ns.html and ie.html (and any images used).
<p>Help should display the following table of contents<br>
</p>
<center>
<table border="1" cellpadding="0" width="100%" bgcolor="#c0c0c0">
<caption><br>
<center></center>
</caption><tbody>
</tbody> <tbody>
<tr>
<td width="808" height="137"><font size="-1">
Compiling</font>
<p><font size="-1">
Java files</font> </p>
<blockquote><b><font size="-1">JavaScript</font></b>
<blockquote><b><font size="-1">Netscape</font></b>
<p><b><font size="-1">IE</font></b></p>
</blockquote>
</blockquote>
<font size="-1">
C++ files</font></td>
</tr>
</tbody>
</table>
</center>
<h4> Scenario 4: basic bottom-up integration</h4>
A typical scenario for a third party ISV is to provide tools (plugins)
and attempt to integrate their documentation with that of the target product
(like IBM's Websphere Studio). For that to happen, the ISV toc file must
link itself to the target toc, and the target doc must expose an anchor for
linking.
<p>The markup for this kind of linking is simply
specifying the link_to attribute on the <toc> element inside the table
of contents file: </p>
<p><toc label="PluginA docs" <b>link_to="../PluginB/toc.xml#anchor_id"</b>
> </p>
<p>The net effect should be the same as if the
target navigation file <link>-ed the ISV navigation component at the
specified anchor. </p>
<p> </p>
<p>Here are the files: </p>
<p>plugin.xml in PluginA and PluginB </p>
<div align="Right">
<table border="1" cellpadding="0" width="100%">
<caption><br>
<div align="Right"></div>
</caption><tbody>
</tbody> <tbody>
<tr>
<td bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1">
<plugin id="PluginA"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<extension point="org.eclipse.help.toc"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<toc file="toc.xml"/></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</extension></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</plugin></font></div>
</td>
<td bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1">
<plugin id="PluginB"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<extension point="org.eclipse.help.toc"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<toc file="toc.xml"/></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</extension></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</plugin></font></div>
</td>
</tr>
</tbody>
</table>
</div>
toc.xml in PluginA and PluginB
<div align="Right"><br>
<table border="1" cellpadding="0" width="100%">
<caption><br>
<div align="Right"></div>
</caption><tbody>
</tbody> <tbody>
<tr>
<td width="50%" bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1">
<toc label=" PluginA Documentation"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<topic label="Compiling" href="docs/compile.html"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<topic label="Java files" href="docs/java.html"/></font></div>
<div style="line-height: 100%; "><b><font size="-1">
<anchor id="other"/></font></b></div>
<p style="line-height: 100%; "><font size="-1">
<topic label="C++ files" href="docs/cpp.html"/></font></p>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</topic></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</topic></font></div>
</td>
<td valign="Top" width="50%" bgcolor="#c0c0c0">
<div style="line-height: 100%; "><font size="-1">
<toc label=" PluginB Documentation" <b>link_to="../PluginA/toc.xml#other"</b>
></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<topic label="JavaScript" href="js.html"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<topic label="Netscape" href="ns.html"/></font></div>
<div style="line-height: 100%; "><font size="-1">
<topic label="IE" href="ie.html"/></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</topic></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</topic></font></div>
</td>
</tr>
</tbody>
</table>
</div>
The following table of contents is built:
<center></center>
<table border="1" cellpadding="0" width="100%" bgcolor="#c0c0c0">
<caption><br>
<center></center>
</caption><tbody>
</tbody><tbody>
<tr>
<td width="808" height="137"><font size="-1">
<font size="-1">Compiling</font></font>
<p><font size="-1">
Java files</font></p>
<blockquote><b><font size="-1">
JavaScript</font></b>
<blockquote><b><font size="-1">
Netscape</font></b>
<p><b><font size="-1">
IE</font></b></p>
</blockquote>
</blockquote>
<blockquote><font size="-1">
C++ files</font></blockquote>
</td>
</tr>
</tbody>
</table>
<h2></h2>
<br>
<h2> REFERENCE</h2>
<h3> Plugin.xml</h3>
A plugin can contribute one or more tables of contents. Tables of contents
files contain navigation info for the help content, i.e.a hierarchical structure
of topic nodes that point to the actual html help documents. By default
tables of contents are meant to be integrated to other tables of contents.
Some are considered standalone or master tables of contents, and marked as
primary. Each TOC contributed by a plugin must be defined in the plugin.xml
file under the org.eclipse.help.toc extension point. A plugin can configure
one or more toc extension points, and each toc extension point can define
one or more tables of contents. Multiple TOCs are contributed when needed
to support different navigation views, or to provide reusable table of contents
components. The same TOC should not be defined multiple times. <br>
The DTD for the org.eclipse.help.toc extension point content is as follows:
<p><font size="-1"><!ELEMENT
extension (toc)* ></font> <br>
<font size="-1"><!ATTLIST
extension point CDATA "org.eclipse.help.toc" #FIXED></font>
<br>
<font size="-1"><!--</font>
<br>
<font size="-1">Each
toc extension point can define any number of toc files.</font> <br>
<font size="-1">--></font>
</p>
<p> </p>
<p><font size="-1"><!ELEMENT
toc EMPTY></font> <br>
<font size="-1"><!ATTLIST
toc file CDATA #REQUIRED></font><br>
<font size="-1"><!ATTLIST
toc primary (true | false) "false" ></font><br>
</p>
<p>
<font size="-1"><!--</font> <br>
<font size="-1">Each
toc file definition specifies the toc file by its relative path (href)
to the plugin and whether the plugin contributes it as a section or a table
of contents or as a standalone or master table of contents.</font><br>
<font size="-1">--></font>
<br>
<br>
</p>
<p>Example: <br>
</p>
<blockquote>
<div style="line-height: 100%; ">
<br>
<table border="1" cellspacing="2" cellpadding="2" width="100%">
<caption><br>
</caption><tbody>
</tbody> <tbody>
<tr>
<td valign="Top" bgcolor="#cccccc">
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<extension point="org.eclipse.help.toc<b>"</b>><br>
</font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<!-- this defines a standalone table of contents --><br>
<toc file="toc.xml" primary="true"/></font></div>
</blockquote>
<div style="line-height: 100%; "><font size="-1">
</extension><br>
<br>
</font></div>
<div style="line-height: 100%; "><font size="-1">
<extension point="<b> org.eclipse.help.toc</b>"></font></div>
<blockquote>
<div style="line-height: 100%; "><font size="-1">
<!-- this defines two sections --></font><b><font size="-1"><br>
<toc file=</font></b><font size="-1">"tocWSAD.xml"/</font></div>
<br>
<font size="-1">
<<b>toc href</b>="referencesWSAD.xml" /></font></blockquote>
<div style="line-height: 100%; "><font size="-1">
</extension></font></div>
<div style="line-height: 100%; "><font size="-1">
</font></div>
</blockquote>
</td>
</tr>
</tbody>
</table>
</div>
</blockquote>
<h3> Toc.xml</h3>
The new table of contents files combine the 1.0 topics files with the
1.0 action files in a cleaner document/web centric structure. <br>
In its most basic form, tables of contents are just hierarchical
structures of topics. A topic is really a "pointer" to the actual help file.
Stepping up in complexity, a table of contents can <b>link </b>other
tables of contents when desired, creating larger tables of contents. Conversely,
a table of contents can <b>link to</b> another table of contents, forming
larger navigation tables of contents in a bottom up approach. Linking to
another table of contents file is done by specifying an anchor in the target table of contents file.<br>
Since topics behave like pointers to a help file, the same html help file
can be reused in many places, by defining the appropriate topic. Reuse can
also be done in groups of topics, with the table of contents file acting as
a reusable component.The same table of contents file can be linked many times.
Two branches of the navigation tree will look identical from the reused table
of contents and down.
<p>The DTD for the
table of contents file follows: </p>
<p><font size="-1">
<!ELEMENT toc (topic | anchor | link)* ></font>
<br>
<font size="-1">
<!ATTLIST toc link_to CDATA #IMPLIED></font>
<br>
<font size="-1">
<!ATTLIST toc label CDATA #REQUIRED></font>
<br>
<font size="-1">
<!--</font> <br>
<font size="-1">
A toc element is the root of the tree of topics defined in the table of
contents file. It can optionally attach to another topics file by providing
its "link_to" attribute. The value of this attribute should be an href to
an anchor defined in this plugin or in another plugin.</font> <br>
<font size="-1">
Href's to anchors in a table of contents in other plugins
are specified as ../other_plugin_id/path_to_toc_file.xml#anchor_id</font><br>
<font size="-1">
Each toc element must define a label to be used in its presentation. The
label is only shown when the table of contents is primary and not integrated
into another table of contents (i.e. it is part of the library of the tables
of contents for the product). When linked, the toc element gets bypassed,
and its topics are directly connected to topics at the link point .</font>
<br>
<font size="-1">
A TOC file consist of any number of (nested) topics, anchor
points or links of other TOC files.</font> <br>
<font size="-1">
--></font> </p>
<p><font size="-1">
<!ELEMENT topic (topic | anchor | link )* ></font> <br>
<font size="-1">
<!ATTLIST topic label CDATA #REQUIRED></font>
<br>
<font size="-1">
<!ATTLIST topic href CDATA #IMPLIED></font>
<br>
<font size="-1">
<!--</font> <br>
<font size="-1">
Each topic is a node in a table of contents tree and can contain topics, anchor points
or can include the topics form other tables of contents.</font><br>
<font size="-1">
For presentaton purposes, each topic must have a label.</font> <br>
<font size="-1">
Most topics have a corresponding help content, identified by the href
value. In general the href is a relative path to a file in the same plugin
(in doc.zip or a regular file) or can point to content in another plugin
using the ../another_plugin_id/path_to_content_file.html form.</font> <br>
<font size="-1">
Topics with no href are there for grouping other topics, for cleaner
tree presentation.</font> <br>
<font size="-1">
--></font> </p>
<p><font size="-1">
<!ELEMENT anchor EMPTY></font> <br>
<font size="-1">
<!ATTLIST anchor id ID #REQUIRED></font>
<br>
<font size="-1">
<!--</font> <br>
<font size="-1">
An anchor is really an insertion point for other tables of contents
to link into the structure defined in the current file. If multiple
topics files linked to the same topic, they will be linked in the processing
order. In other words, the order is not guaranteed. Multiple, adjacent anchors
may be used to differentiate among topics that should be linked before or
after the others.</font> <br>
<font size="-1">
--></font></p>
<p><font size="-1">
<!ELEMENT link EMPTY></font><br>
<font size="-1">
<!ATTLIST link toc CDATA #REQUIRED></font><br>
<font size="-1">
<!--</font><br>
<font size="-1">
A link is used to link the topics from another table of content</font>
s.<br>
<font size="-1">
--></font></p>
<p><br>
</p>
<p><!--ELEMENT include EMPTY--><!--ATTLIST include href CDATA #REQUIRED--><!--
An include is the simplest way to extend navigation by integrating other
topics files available at the place where the element is defined.
The topic's structure (all topic elements) defined in the file specified by the
href attribute is inserted into the current file. This includes all the attached or included
topics files, recursively.
-->
</p>
<h3></h3>
</body>
</html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |