Generating a web-based help tutorial

This page describes the basic steps in converting an Eclipse help system to a web-based help that can be viewed in a browser:
    The help file generator takes Eclipse documentation pages and converts them into a set of web-ready HTML pages. Each page is copied from the Eclipse documentation and placed in the same directory structure to preserve internal links. Then the user-defined template is applied to each page, inserting a header, breadcrumb path, navigation bar and footer around the content.

    Basic steps in converting an Eclipse help system to a web-based help:
    1. Write a template for the documentation pages
    2. Write the generating ant script
    3. Execute the ant script

    1. Write a template for the documentation

    Create a directory (name it headless, for example). Create a file template_simple.html in the directory with the following input.

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
    <html><head>

    <!-------------------------------------------------------------------------------------------->
    <!--                                     SAMPLE TEMPLATE                                    -->
    <!--                 FOR USE WITH WEB GENERATION FEATURE OF HELP COMPOSER                   -->
    <!--                      (RCP Developer from www.instantiations.com)                       -->
    <!--                                                                                        -->
    <!-- How to use:                                                                            -->
    <!-- 1. Duplicate this template.                                                            -->
    <!-- 2. Edit your copy to make it fit your site...                                          -->
    <!--    You can edit any of the HTML; just retain the three <EmbedFromOriginal> areas.      -->
    <!--    They're where material from Eclipse help pages will be inserted by the generator.   -->
    <!-- 3. Use your template in the ant script as described in the Help Composer documentation.-->
    <!--                                                                                        -->
    <!-- Suggestions for editing this template                                                  -->
    <!-- a. Simplest: edit the text in the header and footer.                                   -->
    <!-- b. More complex: also change header and footer appearance in the CSS                   -->
    <!--    style sheets (below in <head>).                                                     -->
    <!-- c. Most customized: Replace everything around the three <EmbedFromOriginal> areas      -->
    <!--    with your own look-and-feel.                                                        -->
    <!--    Note: product documentation on the www.instantiations.com was created in this way.  -->
    <!--                                                                                        -->
    <!-------------------------------------------------------------------------------------------->

    <!-- EmbedFromOriginal area="title" --><!-- EndEmbed -->

    <style type="text/css">

    /* -----------------------------------------------------------------------------------------
        CSS for positioning describes the four DIVs in the layout:
         -- header across the top and footer across the bottom
         -- left-side pane for nav tree and right-side pane for content of the help page.
        NOTE: You are not required to put the Embed areas in these DIVs (if you know how to
        use HTML for layout, you can reorganize the page).
       --------------------------------------------------------------------------------------- */

    #header {
        background-color: gray;
        text-align: center;
        font-size: 20px;
        clear: both;
        padding: 20px;
        }

    #footer {
        background-color: gray;
        text-align: center;
        font-size: 20px;
        clear: both;
        padding: 20px;
        }

    #breadcrumbs-section {
        background-color: silver;
        padding: 12px;
        }

    #nav-tree-section {
        background-color: orange;
        width: 220px;
        float: left;
        padding: 10px;
        }

    #content-section { /* you can control background, etc, of right pane here */
        padding: 20px;
        }

    /* ---------------------------------------------------------------------------------------
        CSS for specific paragraph styles that will be generated in the nav tree.
        Entries in the tree will be enclosed in P tags with class=node
       (except that the entry for the page you are on will have class=node-this).
       --------------------------------------------------------------------------------------- */

    .node {
        font-family: Arial, Helvetica, sans-serif;
        }

    .node-this {
        font-weight:bold;
        font-family: Arial, Helvetica, sans-serif;
        }

    /* ---------------------------------------------------------------------------------------
        CSS for specific text styles that will be generated in the breadcrumbs.
        Entries in the breadcrumbs paragraph will be surrounded with SPAN tags with class=level
       (except that the last entry for the page you are on will have class=level-last).
       --------------------------------------------------------------------------------------- */

    .level {
        font-family: Arial, Helvetica, sans-serif;
        font-size: 12px;
        }

    .level-last {
        font-family: Arial, Helvetica, sans-serif;
        font-size: 12px;
        }

    </style></head><body>

    <!-------------------------------------------------------------------------------------------->
    <!--     actual page content                                                                -->
    <!-------------------------------------------------------------------------------------------->

    <!-- HEADER -->
    <div id="header">Your Header Here</div>

    <!-- BREAD CRUMBS  Generator will embed one paragraph with links to pages in the hierarchy  -->
    <div id="breadcrumbs-section">
    <!-- EmbedFromOriginal area="breadcrumbs" -->
    This text will be replaced by breadcrumbs (links to named pages) such as TopLevel &gt; Section &gt; Subject
    <!-- EndEmbed -->
    </div>

    <!-- NAVIGATION TREE   Generator will embed one parag per entry in Eclipse Help's tree      -->
    <div id="nav-tree-section">
    <!-- EmbedFromOriginal area="navTree" -->
    <p class="node">Replaced by tree entry</p>
    <p class="node-this">Replaced by tree entry</p>
    <p class="node">Replaced by tree entry</p>
    <!-- EndEmbed -->
    <p><i>Documentation generated<br>from the Eclipse Help<br>for the product</i></p> <!-- optional P -->
    </div>

    <!-- CONTENT   Generator will embed Help page's content, retaining its HTML formatting      -->
    <div id="content-section">
    <!-- EmbedFromOriginal area="content" -->
    <p>This text will be replaced by the main contents of the source Help page.</p>
    <!-- EndEmbed -->
    </div>

    <!-- FOOTER -->
    <div id="footer">Your Footer Here</div>

    </body></html>

    2. Write the generating ant script

    In the same directory, create the following ant script file named contact_manager.xml.  This ant file gives all the instructions to the generator such as a template to use (see previous step) and an export directory for the generated files. For the complete documentation on these ant script parameters, see eclipsetools.generateDocumentation.

    <?xml version="1.0" encoding="UTF-8"?>
    <project name="tasks" default="main" basedir=".">
        <target name="main">

            <!-- Define a variable with the path to the Eclipse workspace with     HelpComposer installed: -->
            <property name="workspace.path" value="C:\eclipse\workspace" />
           
            <!-- Generate Contact Manager Help Website -->
            <eclipsetools.generateDocumentation
               
                <!-- The name of the primary Eclipse Help project: -->
                primary = "com.instantiations.contactmanager.help"
               
                <!-- The export directory to write the generated files to: -->
                destinationDirectory = "C:\tempContactManager"
               
                <!-- The location of the template (see previous step) -->
                templateFile = ".\template_simple.html"
               
                <!-- The title prefix and postfix text for each generated webpage: -->
                titlePrefix = "Contact Manager Documentation: "
                titlePostfix = " - Instantiations Example" >
               
                <!-- List of projects and referenced files within each project: -->
                <project name="com.instantiations.contactmanager.help">
                    <fileset dir="${workspace.path}\com.instantiations.contactmanager.help\html" />
                </project>

            </eclipsetools.generateDocumentation>
           
        </target>
    </project>

    The ant script is now launched headlessly. In Windows a batch file to launch the file would look like the following contact_manager_run.bat (with the system-specific java paths input):

    echo off
    setlocal

    REM ***** Local Environment Variables ***********

    REM The JRE java.exe to be used
    set JAVAEXE="C:\java\j2sdk1.4.2_08\jre\bin\java.exe"

    set JAVAPARAMS=""

    REM The Eclipse startup.jar
    set STARTUPJAR="C:\eclipse\startup.jar"

    REM The location of your workspace
    set WORKSPACE="C:\eclipse\workspace"

    REM ****************************************************

    if not exist %JAVAEXE% echo ERROR: incorrect java.exe=%JAVAEXE%, edit this file and correct the JAVAEXE envar
    if not exist %JAVAEXE% goto done

    if not exist %STARTUPJAR% echo ERROR: incorrect startup.jar=%STARTUPJAR%, edit this file and correct the STARTUPJAR envar
    if not exist %STARTUPJAR% goto done

    :run
    @echo on
    %JAVAEXE% -cp %STARTUPJAR% org.eclipse.core.launcher.Main -clean -noupdate -application org.eclipse.ant.core.antRunner -data %WORKSPACE% -verbose -file contact_manager.xml %* >contact_manager_out.txt 2>&1

    :done

    3. Execute the ant script

    After contact_manager_run.bat has been updated with the correct location of Eclipse and workspace, the bat file can be launched.  The generated browser-based pages appear in the destinationDirectory as defined above. With this particular template, the pages have the following appearance. Note the similarities and differences to the Eclipse based pages.

    Web-based Help Example

    At Instantiations, we use this method with a template that's customized for color, header and footer, paragraph styles, and more. Here's a sample result:

    Web-based Help

    For more examples of such websites see the documentation links from http://www.instantiations.com/rcpdeveloper/docs.html.
    Web-based Help

    For more examples of such websites see the documentation links from RCP Developer Documentation.