org.eclipse.help.examples.ex1/readme.html
Parent Directory
| 
Revision Log
Revision 1.6 -
(download)
(as text)
(annotate)
Wed May 17 19:21:22 2006 UTC (3 years, 6 months ago) by curtispd
Branch: MAIN
CVS Tags: v20060518, I20060605-1430, R3_2_1, R3_2_2, R3_2, v20060602, v20060607, HEAD
Changes since 1.5: +10 -10 lines
Wed May 17 19:21:22 2006 UTC (3 years, 6 months ago) by curtispd
Branch: MAIN
CVS Tags: v20060518, I20060605-1430, R3_2_1, R3_2_2, R3_2, v20060602, v20060607, HEAD
Changes since 1.5: +10 -10 lines
fix chkpii errors
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <LINK REL="STYLESHEET" HREF="book.css" CHARSET="ISO-8859-1" TYPE="text/css"> <title>Help System Example</title> </head> <body> <H2>Help System Example</H2> <P>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.</P> <H2>Making the plug-in and content</H2> <P>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.</P> <BLOCKQUOTE><TT>html/</TT><BR> <TT> 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> <P>Create a plug-in directory called org.eclipse.help.example.ex1 and place the above <CODE>html/</CODE> sub-tree into it. Now create an initial plugin.xml file with the following content:</P> <BLOCKQUOTE><TT><?xml version="1.0"?></TT><BR> <TT><plugin</TT><BR> <TT> name = "Online Help Sample"</TT><BR> <TT> id = "org.eclipse.help.example.ex1"</TT><BR> <TT> version = "1.0"</TT><BR> <TT> provider-name = "Eclipse.org></TT><BR> <TT></plugin></TT><BR> </BLOCKQUOTE> <H2>Topics & HTML Content</H2> <P>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> <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> <P><B>toc_Concepts.xml</B></P> <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> <P><B>toc_Ref.xml</B></P> <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> <P>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.</P> <H2>Creating a book</H2> <P>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></P> <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> <P>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. <BR> </P><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> <P>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:</P> <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> <P>That's it, you're done. Now take your 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 this very document. Just don't enter an infinite loop. <BR> <BR> </P> <P> 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> <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> <P>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"</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 for Japanese could be:<BR> <BR> <TT> org.eclipse.help.example.ex1/<BR> nl/<BR> <EM>ja</EM>/<BR> <EM>html</EM>/<BR> </TT> <BR> </P> <H2>Server and doc.zip files</H2> <P>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 start with the HTML files in subdirectories of the plug-in directory. The complete plug-in is jarred during build process. The plug-in will remain jarred when installed in Eclipse.</P> <P>Alternatively, we could decide for the plug-in to be unpacked in a product and rum from a directory. This will happen if a feature delivering our plug-in does not have the "unpack" attribute to "false" for this plug-in in the feature manifest. In that case, it is recommended to package HTML files, with the corresponding images, into a doc.zip file, placed at a root of the plug-in.<BR> </P> </body> </html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |