diff options
Diffstat (limited to 'Article-Online Help for 2_0/help1.htm')
| -rw-r--r-- | Article-Online Help for 2_0/help1.htm | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/Article-Online Help for 2_0/help1.htm b/Article-Online Help for 2_0/help1.htm new file mode 100644 index 0000000..e5131a1 --- /dev/null +++ b/Article-Online Help for 2_0/help1.htm @@ -0,0 +1,358 @@ +<!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="Author" content="Greg Adams"> + <meta name="Author" content="Dorian Birsan"> + + <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, 2003 Object Technology International, Inc.</font></font></div> + +<div align="right"> +<table border="0" cellspacing="0" cellpadding="2" width="100%"> + <tbody> + <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> + + </tbody> +</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 Platform’s help system defines two extension points (<code> + "toc" </code>and<code> "contexts"</code>) that allow individual plug-ins to +contribute online help and context-sensitive help for their components. +In this article we will investigate the <code>"toc"</code> 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 August 9, 2002</font></p> +<p>Editor's note: This article describes the help system for Eclipse release 2.1, + which differs in minor ways from the previous Eclipse release. If you are working + with Eclipse release 1.0, you should consult <a href="../Article-Online%20Help%20for%201_0/help1.htm">the + original version of this article</a>.</p> +<center> + <hr size="2" width="100%" align="center"></center> + +<h2> Introduction</h2> + The Eclipse Platform’s help system allows you to contribute your plug-in’s + online help using the org.eclipse.help.toc 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 Platform’s help facilities provide you with +the raw building blocks to structure and contribute your help without +dictating the structure or granularity of documentation. The Platform +does however provide and control the integrated help viewers thus ensuring + seamless integration of your documentation. <br> +<br> +The org.eclipse.help.toc contribution specifies one or more associated + XML files that contain the structure of your help and its integration with +help contributed by other plug-ins. In the remainder of this article we +will create a documentation plug-in, so by the time your're done you can +browse your own documentation using the Eclipse Help System. +<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 or on their content. We will start by assuming +that you already have some HTML files that you want to integrate into the +Eclipse Platform. Let’s assume your content is arranged into the following +directory tree. +<blockquote><tt>html/</tt><tt> <br> + overview.html</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 <code>html/</code> sub-tree into it. 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 = "1.0"</tt><br> + <tt> provider-name = "Eclipse.org></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> toc </b>file. A toc file defines the key entry points into the +HTML content files by defining labeled topics mapped to the individual +HTML files. A toc file acts like a table of contents for a set of HTML content. +Teams migrating onto the Eclipse Platform can quickly reuse existing HTML +documentation by defining entry points into their existing documentation +via the toc file. A plug-in can have one or more toc files. Toc 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 toc file, or a toc 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 toc file for each of the three +content areas as follows: +<p class="MsoNormal"><b>toc_Tasks.xml</b></p> + +<blockquote><tt><toc label="Tasks"></tt><br> + <tt> <topic label="Plain Stuff"></tt><br> + <tt> <topic label="Task1" + href="html/tasks/task1.html"/></tt><br> + <tt> <topic label="Task2" + href="html/tasks/task2.html"/></tt><br> + <tt> </topic></tt> <tt> + <br> + <topic label="Fun Stuff" ></tt><br> + <tt> <topic label="Task3_1" + href="html/tasks/task3_1.html"/></tt><br> + <tt> <topic label="Task3_2" + href="html/tasks/task3_2.html"/></tt><br> + <tt> </topic></tt><br> + <tt></toc></tt></blockquote> + <b>toc_Concepts.xml</b> +<blockquote><tt><toc label="Concepts"></tt><br> + <tt> <topic label="Concept1" href="html/concepts/concept1.html"></tt><br> + <tt> <topic label="Concept1_1" + href="html/concepts/concept1_1.html"/></tt><br> + <tt> <topic label="Concept1_2" + href="html/concepts/concept1_2.html"/></tt><br> + <tt> </topic></tt><tt><br> + </toc></tt></blockquote> + <b>toc_Ref.xml</b> +<blockquote><tt><toc label="Refs"></tt><br> + <tt> <topic label="Ref1" href="html/ref/ref1.html"/></tt><br> + <tt> <topic label="Ref2" href="html/ref/ref2.html"/></tt><br> + <tt></toc></tt></blockquote> + Topics are contributed as part of the <code><toc></code> container element. + A <code><topic></code> 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 used as a link, the argument to href is assumed to be +relative to the current plug-in. Later we will modify the plugin.xml to +add the actual contributions consisting of these files. Notice that the +hierarchical structure of topics is not the same as the file system structure: +all the "Concepts" topics files in one directory, but the table of contents +nests them differently. + +<h2> Creating a book</h2> + Now that we have our raw content and toc files it’s time to create +our book. A book is just table of contents. In fact, we could make a book +out of each of the three toc files above, but we will treat them as sections +of a larger book instead. So, we will create another toc file that defines +the main sections of the book and will link the three toc files above to +create a larger table of contents (our book).<br> + <br> + <b>book.xml</b> +<blockquote><tt><toc label="Online Help Sample" topic="html/book.html"></tt><br> + <tt><topic label="Overview" + href="html/overview.html"/></tt><br> + <tt> <topic label="Concepts"></tt><br> + + <tt><<b>link toc="toc_Concepts.xml"/></b></tt><br> + <tt></topic></tt><br> + <tt> <topic label="Tasks"></tt><br> + <tt> <<b>link toc="toc_Tasks.xml</b>"/></tt><br> + <tt> </topic></tt><br> + <tt><topic label="Reference"></tt><br> + <tt> </tt><tt><<b>link + toc="toc_Ref.xml"</b>/></tt><br> + <tt> </topic></tt><br> + <tt></toc></tt></blockquote> + The Eclipse Platform can display any number of books/tables of contents. + Each table of contents 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 + we’ll 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> + The following figure shows the book called "Online Help Sample" in +the list of all available books.<br> + <br> + +<blockquote><img src="books.jpg" alt="books" width="677" height="505" + border="0"> + <br> + </blockquote> + <br> + +<h2> Finishing our plug-in</h2> + +<p><br> + The one remaining piece of work is to update our plugin.xml to actually + contribute the toc files that we created. Start with updating the plugin.xml + to contribute our book. The important thing here is to define this table + of contents as a primary <code><toc></code>.</p> + +<blockquote><tt><extension point="org.eclipse.help.toc"></tt><br> + <tt> <toc file="book.xml" <b>primary="true"</b> + /><br> + </extension><br> + </tt></blockquote> + Next we contribute the section toc files, and the important thing +here is that primary is not set, so its default value (false) gets picked +up: + +<blockquote><tt><extension point="org.eclipse.help.toc"></tt><br> + <tt> <toc file="toc_Concepts.xml" + /></tt><br> + <tt> <toc file="toc_Tasks.xml" /></tt><br> + <tt> <toc file="toc_Ref.xml" /></tt><br> + <tt></extension></tt></blockquote> + That’s it, you’re done. Now take your plug-in (click here for a <a + href="final.zip"> zip file</a> of the final plug-in) and drop it +into the Platform’s <i>plugins</i> directory, start Eclipse and choose +Help -> Help Contents. Once you select the Online Help Sample and expand +the topics you will see the following. <br> + + <br> + +<blockquote><img src="expanded_book.jpg" alt="expanded book" width="631" + height="520"> + </blockquote> + +<p><br> + Before we continue a brief recap is in order: </p> + +<ul> + <li> We started by creating our plug-in and document + files.</li> + <li> Next we created toc files to describe the structure/navigation + of our content.</li> + <li>We then created the toc file for the book and linked + the other toc files as sections of the book.</li> + <li>Finally we contributed all the files in the + plugin.xml in the org.eclipse.help.toc extension point.<br> + </li> + +</ul> + +<p> </p> + +<h2>Integration of Tables of Contents</h2> + +<div align="left">In our example we defined four tables of contents, of which +one was viewed as the book, the other three as sections of the book. Since +the book is aware of what sections to link we call this a top-down integration. +It is possible to do it the other way around, i.e. bottom-up integration, +where the sections specify which book (or section) to link to. A table of +contents indicates its willingness to allow others to link to by providing +anchors (<anchor id=..."/>) at the desired linking points.<br> + Most often a plug-in defines a primary table of contents to which other plug-ins +integrate their own table of contents. Tables of contents that are not primary +or are not (directly or indirectly) integrated into other primary tables of +contents are discarded from the final help navigation.<br> + Linking is specified by using the fully qualified reference to a table of +contents, such as<br> + +<ul> + <li>top-down: <link toc="../the_other_plugin_id/path/to/toc.xml" +/> or</li> + <li>bottom-up: <toc link_to="../the_other_plugin_id/path/to/toc.xml#anchor_id"/><br> + </li> + +</ul> + </div> + +<p>Since the participating tables of contents are sometimes located in other +plug-ins, and these plug-ins may not be installed, it is possible that some +tables of contents remain unintegrated.<br> + 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 book is +visible. When topics from a plug-in are integrated into a larger web it +probably doesn’t make sense for their standalone book to show up anymore. + To support this nonintegrated or loosely integrated documentation, a plug-in + can define a table of contents as a book by setting its <b>primary</b> + attribute to true (inside plugin.xml) and having a <b>link_to </b>attribute +pointing to the desired anchor in the larger web. This has the effect of the +table of contents appearing as a book when the plug-in defining the anchor +is not installed, and appearing as a section of the target book when the plug-in +defining the anchor is installed.<br> +<br> + </p> + +<h2>Localization</h2> + Plugin manifest 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> + <br> +Strings from the contribution XML files and the topic HTML files are not +externalized. The toc XML files and the HTML documentation must be translated +and packaged in the appropriate NL directory structure or in an NL fragment, + making sure files do not change their names. The NL directory structure +inside a plug-in is <br> +<br> +<tt> myplugin/<br> + nl/<br> + <em>langCode</em>/<br> + +<em>countryCode</em>/<br> +</tt> <br> +Here is how the plug-in with Japanese documentation is <a href="final_ja_JP.zip">packaged</a> (note: the files are not translated, +just packaged in the appropriate location). + +<h2> Server and zip files</h2> + The Platform utilizes its own help server to provide the +actual web pages from within the document web. A help server +allows the Platform to handle the wide variety of web browsers in a browser +independent way while also providing plug-in aware support. The Platform's +help server allows the documentation to also be packaged in zip files +thus avoiding problems that may result when a large number of files are +present. In our example, we put the HTML files in subdirectories of the plug-in directory. +Alternatively, we could have placed them in a .zip file, called doc.zip, in the plug-in directory, +maintaining the directory structure underneath. In general, the recommended way is to actually zip all the documentation. +Here is how the plug-in is <a href="zipped_plugin.zip">packaged.</a><br> + + +<h2> Conclusions</h2> + We have seen how we can use the tables of contents to declare books +the user can see. We then used the linking mechanism to integrate our topics. +The Platform’s 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/books onto +your documentation web. In our plug-in we only created a single book but +additional books could easily be created. Lastly, we observed that the Platform +provides the building blocks for documentation integration, provides minimal packaging guidelines, +and lets the documentation authors have full control over structuring their HTML files. <br> + <br> + + <br> + <br> +</body> +</html> + +<!-- ZoneLabs Popup Blocking Insertion --> +<script language='javascript'>postamble();</script> |