Click here to Skip to main content
14,975,416 members
Articles / Web Development / HTML
Article
Posted 24 Aug 2018

Stats

10.1K views
5 bookmarked

Documenting Your Project Using the Eclipse Help System

Rate me:
Please Sign up or sign in to vote.
5.00/5 (5 votes)
30 Aug 2018CPOL7 min read
Any project can use a cut-down version of the platform to provide professional, easy-to-use, and searchable documentation

Introduction

When you access the Eclipse help system (through Help > Help Contents), you are actually starting up an embedded Apache Tomcat server. A window based on a Web browser is then opened, pointing to the correct page on that server (see Figure 1). Documentation is provided with a collapsible index on the left side and HTML documentation on the right, and can be searched (thanks to the Apache Lucene search engine). Since Tomcat is used, you are not limited to HTML. For example, you can use JSPs to make your documentation change dynamically (though we will discuss later a possible reason to avoid doing this).

Image 1

Figure 1. Example of Eclipse help

Installing Eclipse Plug-in Development Environment (PDE)

You must install the eclipse IDE for Java developers. You can install Eclipse Commiters version that contains PDE installed by default.

For Eclipse IDE for Java Developers Mars, go to:

  1. Choose Help > Check for Updates from the Eclipse menu bar before continuing
  2. Choose Help > Install New Software from the Eclipse menu bar
  3. In field Work with, select "Mars - http://download.eclipse.org/releases/mars"
  4. Expand Eclipse Plugin Development Tools, then select Eclipse Plug-in Development Environment (see Figure 2), then just go to Next, Next, Accept policy, Finish
  5. Restart Eclipse when prompted to do so

Image 2

Figure 2. Installing Eclipse PDE

How Do I Create a PDE Plug-in?

The simplest way to develop and maintain a plug-in is to use the special wizards and editors the PDE provides. Using a wizard, you can generate basic plug-ins with a few mouse clicks.

  1. Choose File > New > Other... from the Eclipse menu bar
  2. Select Plug-in Development > Plug-in Project (see Figure 3) > Next

    Image 3

    Figure 3. Creating a new Plug-in Project
  3. Choose a suitable name for your plug-in (see Figure 4). Most Eclipse plug-in names start with org.eclipse, but you can choose any suitable name here. Click Next.

    Image 4

    Figure 4. Project name
  4. Check the box Create a plug-in using one of the templates (see Figure 5)
  5. Select Plug-in with sample help content > Next

    Image 5

    Figure 5. PDE Template
  6. Select Plug-in with sample help content > Next. Accept all the defaults following in the next wizard pages by clicking Next.
  7. Select the plugin.xml file at the left panel.
  8. Click on Extensions tab and click Add... (see Figure 6)

    Image 6

    Figure 6. Adding Sample Content
  9. Click on Generate a primary table of contents for testing > Finish (see Figure 7)

    Image 7

    Figure 7. Sample Help of Contents

The Hello, World of Documentation Plug-ins

Documentation is split into "books", and you can have as many books as you like in one instance of the help system. Each book is written as an Eclipse plug-in, but thankfully, the work involved here is minimal. To write a simple plug-in, you will need a plugin.xml file to describe your plug-in, which should look like Listing 1.

XML
<plugin name="Sample Documentation Plug-in" id="com.ibm.sample.doc"
   version="1.0.0" provider-name="IBM">
   <extension point="org.eclipse.help.toc">
      <toc file="toc.xml" primary="true" />
   </extension>
</plugin>

Change the plug-in's name, id, version, and provider-name to values appropriate to your project. The extension point of org.eclipse.help.toc identifies this as a plug-in to the help system. The file toc.xml is referenced as being the table of contents for this plug-in. This file will provide the data for the hierarchical information in the left pane of the Eclipse help window. A simple file contains something like that shown below:

XML
<toc label="Sample Documentation">
    <topic label="My Section" href="mySection.html">
        <topic label="Foo" href="foo.html"/>
        <topic label="Bar" href="bar.html"/>
    </topic>
</toc>

If your project has more than a few people working on it or has a large documentation set, updating a single table of contents (toc.xml) file can become impractical. You can change this by adding a link element into your topic in the main toc.xml file.

XML
<toc label="Sample Documentation">
    <topic label="My Section" href="mySection.html">
        <topic label="Foo" href="foo.html"/>
        <topic label="Bar" href="bar.html">
            <link toc="bar-toc.xml" />
        </topic>
    </topic>
</toc>

The file bar-toc.xml is just another table of contents, and should take exactly the same format as any other toc.xml file. When the documentation is viewed, there will be no difference between using this method and simply including the additional topic elements directly.

Packaging the Plug-in

An Eclipse Help system is made up of:

  • HTML, CSS and supporting image file, generated through the DITA Open Toolkit (or another DITA processor)
  • the plugin.xml file, which defines the location of the Help system, and the file name of the Table of Contents (TOC)
  • a TOC file, which is a simple XML file that specifies the hierarchy and location of the topics in the Help system

Each topic element is represented in the final documentation by an entry in the navigation list. These topics can be nested (they can contain more topics), and each one points to an HTML or JSP file. Once you've done this, all you need to do is package everything in the structure shown in Figure 8 (notice that the plug-in directory name matches the id and version attributes of the plug-in defined in the plugin.xml).

Image 8

Figure 8. Plug-in directory structure

As a convenience, and to reduce file size, Eclipse allows you to keep all your actual documentation (the HTML files) in a ZIP file called doc.zip, so you could use the directory structure shown in Figure 9.

Image 9

Figure 9. Alternative plug-in directory structure

For localization support, you may use the following directory structure:

com.my.plugin/
              plugin.xml
              nl/
                 de/
                    doc_index.zip
                 en/
                    doc_index.zip
                 zh/
                    CN/
                       doc_index.zip
              other files of this plugin

Viewing Your Documentation

  1. Select the plugin.xml file at the left panel (see Figure 6)
  2. Click on Build tab (see Figure 10)
  3. Check the documentation files at Binary Build panel

    Image 10

    Figure 10. Selecting documentation files to build
  4. Into Exporting, click on Export Wizard link (see Figure 11).
  5. Select the directory where you want to save the generated *.jar file and click on Finish

    Image 11

    Figure 11. Building documentation

The easiest way to test your plug-in is to simply drop the *.jar file into the plugins directory of an installed Eclipse Platform, then launch Eclipse and select Help > Help Contents. You will get a help window with your plug-in added (similar to the one in Figure 1).

Standalone Help

Using the IDE is all very well for testing, but to be useful without the IDE, the documentation needs to be more accessible, so what we really want is to run a process in the background that lets us connect to it with a browser. You can allow your users to access the help system over the Internet or an intranet by installing an information center and the documentation plug-ins on a server. Clients view help by navigating to a URL, and the help system is shown in their Web browser.

Eclipse Help systems are delivered through a Web server via Java Server Pages (JSP). The delivery system for Eclipse Help is often called an Eclipse InfoCenter. A standalone Eclipse Help InfoCenter is a self-contained collection of Help files and a bundled Web server with JSP support, without the full Eclipse IDE. The delivery component (including the bundled Web server) is about 80 MB in size (40 MB zipped). That package also includes a dedicated viewing application, which is a cut-down browser (see Figure 4). An Eclipse Help system is technically called a plug-in. An InfoCenter will typically be made up of a number of Help systems (plug-ins).

Image 12

Figure 12. InfoCenter in action

If you are creating an application that is not based on the Eclipse framework, you can still use the Eclipse help system. Your application can package and install the stand-alone help system, a very small version of Eclipse that has everything except the help system stripped out of it. When an application is not Java based, or help is required when the application is not running, it is possible to use stand-alone help from a system shell, a shell script or a desktop shortcut and provide command line options instead of calling Java APIs.

Instructions for starting an InfoCenter process (basically Apache Tomcat) are included with the Eclipse help system documentation (see Related topics). Note that there also instructions on how to pare down the Eclipse system to give you just the bits you need.

Points of Interest

Of course, using the Eclipse help system is all well and good if you don't mind distributing the 40-plus MB of code required. Hosting an InfoCenter on a central server allows people to connect remotely. People receive all the benefits of using the Eclipse help system (such as searching), but people without connectivity are left stranded. So, in addition to using a hosted InfoCenter, it's useful to include the plain HTML in a downloadable package. As long as you haven't used any server-side technologies such as JSPs, you can easily generate an HTML table of contents to replace the XML one used by Eclipse.

Using the Eclipse help system is a fairly painless way to develop professional-looking, searchable documentation that will amaze your friends and colleagues.

References

  1. Documenting your project using the Eclipse help system. IBM Development.
  2. Standalone help. Eclipse Documentation.
  3. Eclipse Standalone Help. Dita Wiki.
  4. FAQ How do I create a plug-in? Eclipsepedia.

Related Topics

  1. Deploying the information center as a Web Archive. Eclipse Documentation.
  2. Standalone help. Eclipse Documentation.
  3. Information Center. Eclipse Documentation.

History

  • 24th August, 2018: Initial version

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

No Biography provided

Comments and Discussions

 
GeneralMy vote of 5 Pin
Likefire4-Sep-18 10:55
MemberLikefire4-Sep-18 10:55 
QuestionThis is not .Net article this is a Java article Pin
Daszbin25-Aug-18 23:51
professionalDaszbin25-Aug-18 23:51 
AnswerRe: This is not .Net article this is a Java article Pin
Eduardo Mozart de Oliveira29-Aug-18 14:02
MemberEduardo Mozart de Oliveira29-Aug-18 14:02 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.