Help content configuration

The optional "helpContent" file allows to configure how the help content will be generated. It specifies how the articles will be regrouped under chapters in the help tree^[1]

By default if this file is not present all articles will be added under the root

.

This XML file also allows to configure the Context-sensitive Help. Note that even if docJGenerator can generate the Help content automatically, it is possible to produce the Help content manually. See Using the Help API with manually produced content.

Overview

The help content file specifies each of the "chapters" and "sub-chapters" in the generated help content. Each "chapter" and "sub-chapter" will be a parent node in the tree. Each chapter can contain:

• "chapter": Its sub-chapters
• "category": One category or a list of categories for the articles to add in the chapter
• "excludeCategory": One category or a list of excluded categories for the articles to not add in the chapter even if they belong to one of the categories in the previous list^[2]
  For example, if a chapter contain the category "general", and the excluded category "general4", articles which are both in the "general" and "general4" categories will not be added in the chapter
• "article": One article to add in the chapter. If an article is in this category
• "excludedArticle": One article to excluded in the chapter

The help content can also specify the references for the Context-sensitive help.

Grammar

See The Help content schema.

Categories

The category element define one category to add in the chapter.

For example, in the following content definition, articles which are in the "general" category will be added in the chapter.

      <chapter name="first chapter">
         <category name="general" />   
      </chapter>

It is possible to use a list of categories for the attribute rather than only one. In this case, it means that only articles belonging to all the listed categories will be added to the chapter.

For example, in the following content definition, articles which are in both the "general" and "general2" category will be added in the chapter.

     <chapter name="first chapter">
        <category name="general general2" />   
     </chapter>

Excluding categories

The excludeCategory element define categories which will be excluded from a chapter even if they belong to one of the categories defined for the chapter.

For example, in the following content definition, articles which are both in the "general" and "general4" categories will not be added in the chapter:

      <chapter name="first chapter">
         <category name="general" />
         <excludeCategory name="general4" />      
      </chapter>

It is possible to use a list of categories for the attribute rather than only one. In this case, it means that only articles belonging to all the listed categories will not be added to the chapter.

For example, in the following content definition, articles which are in both the "general", "general2", and "general4" categories will be added in the chapter. But an article which belong to both the "general" and "general2" categories, but not the "general4" category will be added:

     <chapter name="first chapter">
     <category name="general" />
        <excludeCategory name="general2 general4" />   
     </chapter>

Articles

The article element define an article whcih will be added in the chapter. For example:

      <chapter name="first chapter">
         <article name="first article" />
         <article name="second article" package="thePackage"/>     
      </chapter>

Excluding articles

The excludeArticle element define an article which will not be added in the chapter.

For example, in the following content definition, the "first article" will not be added even if it is in the "general" category.

     <chapter name="first chapter">
        <category name="general" />
        <excludeArticle name="first article"/>     
     </chapter>

Resolving priorities for articles

The priority of chapters resolving for the articles can be changed by setting the "property" attribute. Note that by default the priority for each chapter is defined as 0.

For example, in the following content definition, articles which are in the "general4" will not be added in the "first chapter" chapter but the "second chapter" chapter.

   >helpContent>
     <chapters>
        <chapter name="first chapter">
           <category name="general" />
           <category name="general4" />      
        </chapter>
        <chapter name="second chapter" priority="1" >
           <category name="general4" />
        </chapter>
     </chapters>  
   >/helpContent>    

Keeping the articles order

The keepOrder attribute for the root helpContent element allows to keep the order of articles which are specifically specified for each chapter. For example:

  <helpContent keepOrder="true">
     <chapters>
        <chapter name="first chapter">
           <article name="article d" /> 
           <article name="article b" /> 
           <category name="general" />
        </chapter>
        <chapter name="second chapter">
           <category name="general2" />
        </chapter> 
     </chapters>
  </helpContent>

In that case "article d" will be the first article in the first chapter, and "article b" the second article in the chapter.

Context-sensitive help

The context-sensitive help allows to go to an article in the help system by clicking on a component in the GUI. The Help content allows to specify IDs which will be used to link the elements in the GUI where the user will click and the corresponding articles and titles. Each ref element have the following attributes:

• id: the ID which will allow to make the link between the GUI components and the help content
• article: The name of the article. Note that the references to article names have the same rules as in the wiki. See naming constraints
• articlePackage: optional, specifies the article package
• title: Optionally the title or anchor in the article

For example:

   <helpContent>
      <ref id="button1" article="button 1" />
      <ref id="button2" article="button 2" />      
      <ref id="button3" article="several components" title="button 3" />  
      <ref id="textfield" article="several components" title="text field" />  
      <ref id="panel" article="several components" title="panel"/>  
   </helpContent>

StyleSheet configuration

It is possible to specify several StyleSheet themes in the Help content file. This will allow to customize the StlyeSheet of the help, the theme, or even to specify more than one theme and switch dynamically from one theme to another.





For example:

   <helpContent>
      <styleSheets>
         <styleSheetTheme id="black" url="themeBlack.css"/>
      </styleSheets>
   </helpContent>

Example

Suppose that we have the following content for the file:

  <helpContent>
    <chapters>
       <chapter name="first chapter">
          <chapter name="child chapter">
             <category name="general2" />
          </chapter>
          <category name="general" />
          <category name="general4" />      
       </chapter>
       <chapter name="second chapter">
          <category name="general2" />
          <category name="general3" />
       </chapter>
    </chapters>  
  </helpContent>

Here we have the following specification for the help content:

• There will be the following tree structure: the "first chapter" parent under the root with a "child chapter" sub-node, and the "second chapter" also under the root
• The "first chapter" parent will contain all articles in the "general" category, except those which are also in the "general2" category which will be under the "child chapter" sub-node
• The "second chapter" parent will contain all articles in the "general3" categoriey, and also those in the "general2" category which are not in the "general" category

If we have the following list of articles:

• "article1" in the "general" category
• "article2" in the "general" category
• "article3" in the "general2" category
• "article4" in the "general2" category
• "article5" in the "general" and "general2" categories
• "article6" in the "general3" category
• "article7" in the "general4" category

Then the result will be:

• "first chapter" will contain "article1", "article2", and "article7", and the sub-chapter "child chapter"
• "child chapter" will contain "article5"
• "second chapter" will contain "article3, "article4", and "article6"