Using the Help API with manually produced content

The Help content is a zip file which is automatically generated by the tool, according to the Help content configuration. However it is possible to produce a Help content as a zip or jar file manually.

Help content structure

The XML database must be a zip or jar file containing at least one articles.xml file at the root of the archive. This XML file will refer to the html articles which can be anywhere in the archive. Note that by default there should be two additional files in this archive:

• An index.html file also at the root of the archive, which define the default page of the help content (home page)
• A stylesheet.css Stylesheet file in the resource directory of the archive, which define the Stylesheet to be used for the articles

The default basic structure is:

      HelpContent zip/jar file
      -- articles.xml
      -- resources
      ---- stylesheet.css

However, these defaults can be overriden:

• It is possible to define any entry in the archive as the XML database with the JavaHelpFactory(URL, String) constructor or with the JavaHelpFactory.merge(URL, String) methods to merge content
• It is possible to define any other entry in the archive as the index by JavaHelpFactory.setIndexPath(String)

The articles themselves are referred by the articles.xml database file and can be anywhere in the archive.

Database file structure

The database XML file contains the following elements:

• A list of optional include elements which specify children database indexes
• A list of article elements which specify the name and entry path for each article
• Optionally, a chapters element which specify the chapters in the tree and which articles they contain
• A list of articleID elements which specify the articles which are at the top-level of the help (not under any chapter)
• Optionally, a list of ref elements which specify the ids to use for the Context-sensitive Help

Each chapter also contain a list of articleID elements which specify the articles at the top-level of the chapter, and optionnally, a list of chapter children for the sub-chapters.

Database root

The root of the database may contain the following optional elements:

• An index attribute which specifies the location of the index^[1]
  If This attribute is not present, the index is considered to be at the root of the zip file and be named index.html
• A styleSheet attribute which specifies the location of the StyleSheet file^[2]
  If This attribute is not present, the StyleSheet is considered to be at the root of the zip file and be named stylesheet.css
• A glossary attribute which specifies the location of the glossary file if it exists
• A fullTextSearch attribute which specifies the full text search database^[3]
  Full text search will be enabled in the JavaHelp component if this attribute is set
  . See also full text search

For example:

   <database index="myIndex.html" styleSheet="myCSS.css" glossary="glossary/html" >
   ...
   <database>

Article element

The article element specifies the name of an article (as it will appear in the Help tree and in the autocompletion), and the path of the entry in the corresponding archive. For example:

  <article name="article 1" url="article1.html" />
  <article name="article 2" url="mysubdirectory/article2.html" />

In the case of a Full text search, the element can also have a "header" attribute which will be presented alongside the article name in the search results.

Note that the references to article names have the same rules as in the wiki. See naming constraints.

This element can have altTitle and title children:

• The altTitle element specifies an alternate title which will be used in the autompletion for the article. For example:

     <article name="docgenerator help feature" url="docgenhelp.html" >
       <altTitle name="docgenhelp" />
       <altTitle name="help system" />
     </article>
  

• The title element specifies titles in the article which will be used in the autompletion for the article. For example:

     <article name="docgenerator help feature" url="docgenhelp.html" >
        <title name="API usage" id="api usage" />
        <title name="Overview" id="overview" />
     </article>
  

Chapter element

The chapters element contain the references of the articles which are under this chapter, and optionnaly its sub-chapters. For example:

   <chapter name="Help System" >
      <chapter id="Swing" />
         <articleID id="Swing help" />
      </chapter>
      <chapter id="JavaFX" />
         <articleID id="JavaFX help" />
      </chapter>
      <articleID id="overview" />
      <articleID id="api usage" />
   </chapter>

ArticleID element

The articleID element refer to the name of an article defined in an article element. For example the following article:

  <article name="article 1" url="article1.html" />

Can be referred to by:

   <articleID id="article 1" />

Ref element

The ref element specify an ID for the Context-sensitive Help, which can refer to an article or to an article title. For example:

   <ref id="button2" article="button 2"/>
   <ref id="button3" article="several components" title="button_3"/>

Grammar

See The Help database schema.

XML database examples

Basic example

  <database>
    <article name="article 1" url="article1.html" />
    <article name="article 2" url="mysubdirectory/article2.html" />
    <article name="article 3" url="article3.html">
       <title id="the_title" name="My title" />
    </article>
    <chapters>
       <chapter name="first chapter">
          <chapter name="sub-chapter">
             <articleID id="article 1" />
          </chapter>
       </chapter>
       <articleID id="article 2" />
    </chapters>
    <articleID id="article 3" />
  </database>

Example with context-sensitive help

  <database>
    <article name="article 1" url="article1.html" />
    <article name="article 2" url="mysubdirectory/article2.html" />
    <article name="article 3" url="article3.html">
       <title id="the_title" name="My title" />
    </article>
    <chapters>
       <chapter name="first chapter">
          <chapter name="sub-chapter">
             <articleID id="article 1" />
          </chapter>
       </chapter>
       <articleID id="article 2" />
    </chapters>
    <articleID id="article 3" />
    <ref id="ref1" article="article 1" />
    <ref id="ref2" article="article 3" title="the_title" />
  </database>

Example with children index

  <database>
    <include url="subindex.xml" />
    <article name="article 1" url="article1.html" />
    <article name="article 2" url="mysubdirectory/article2.html" />
    <article name="article 3" url="article3.html">
       <title id="the_title" name="My title" />
    </article>
    <chapters>
       <chapter name="first chapter">
          <chapter name="sub-chapter">
             <articleID id="article 1" />
          </chapter>
       </chapter>
       <articleID id="article 2" />
    </chapters>
    <articleID id="article 3" />
  </database>

Example with full text search

  <database fullTextSearch="fullTextSearch.json" >
    <article name="article 1" url="article1.html" header="the article"/>
    <article name="article 2" url="mysubdirectory/article2.html" header="the article 2" />
    <article name="article 3" url="article3.html" header="the article 3" >
       <title id="the_title" name="My title" />
    </article>
    <chapters>
       <chapter name="first chapter">
          <chapter name="sub-chapter">
             <articleID id="article 1" />
          </chapter>
       </chapter>
       <articleID id="article 2" />
    </chapters>
    <articleID id="article 3" />
  </database>

Checking the content of the Help content archive

The docGeneHelpChecker.jar tool allows to check the content of a Help content archive. It checks that the XML database is valid, and that the articles which are referred exist.