Danny Wahlquist's Mindsay Blog about docbook

Deploying Help Overview

Help documentation is deployed as a set of files zipped up in module jar files. Help content can be any MIME typed file. The primary content types are:

• HTML: Niagara provides support for HTML 3.2 with cascading style sheets. See HTML Support in the User Guide for specific tags and attributes supported. This is the main format used to distribute help content.
• Bajadoc: The Bajadoc format is a special XML file used to distribute reference documentation. Niagara supports a special plugin, the BajadocViewer which allows users to view the reference documentation in a variety of ways. Bajadoc files are generated from Javadoc comments using the build tool.

In addition to help content, the Niagara Framework also supports delivering navigation data using JavaHelp files. Niagara help system is loosely compliant with version 1.0 of JavaHelp specification from Sun Microsystems. By the term "loosely"; we mean that it is compliant with some of its requirements as of version 1.0.

There are three steps in help content creation:

1. Developer supplies help content files and help structure files. Most of help content will be in form of HTML files, maybe with some graphics to enhance the presentation. As a general rule, you as developer should not concern yourself with anything but the content itself, providing HTML files with defined title and body that contains only content-related information.
   Developers should also include guide help for all their BPlugins designed for use by BComponents. This documentation is standard HTML files located in the "doc" directory using a naming convention of "module-TypeName.html".
   You should provide a TOC file, to specify the logical order of the help files.
2. (Optional ) Developer supplies lexicon key to point to module containing help. Guide help (Guide on Target) will look for the HTML file defined above in the doc directory of its module if the help.guide.base is not defined in its lexicon. You can supply this key to point to another module. As an example, most core modules point to docUser:
   help.guide.base=module://docUser/doc
3. Build the module. The module containing the help content is built using the standard build tool. See Using Build. In addition to the standard build, you should use the htmldoc tool to enhance HTML files, and then use the index tool to build search index files. During this step, the help content is indexed for the full text search purposes. For example, to build docDeveloper, we ran this sequence of commands: build /docs/docDeveloper clean build /docs/docDeveloper build /docs/docDeveloper htmldoc build /docs/docDeveloper index

Help Views

The same help content can be presented in many different ways. Each way of presenting help content is called view in JavaHelp lingo. Three most typical views are: Table of Contents, API and Search.

• Table of Contents, a.k.a. TOC, is used for presenting help content in a structured way, in some logical order.
• API is used for presenting bajadoc organized by module.
• Search allows full text search of the help content based on some search criteria.

We have added our own "standard" view - BajaDoc view. This is a way of presenting reference documentation for the module classes.

TOC

As a general rule, you should provide a rough TOC with your help content. This should be an XML file, named toc.xml, located in the doc/ directory. This file is required for a module to appear in the help table of contents. Here's the DTD for this file:

It should have as its root element, and a list of files that you want to include in the final TOC, in the logical order. Although TOC structure can be many levels deep, the most likely case will be a flat list of files.
Each file is included via the element, that has two attributes: text and target. The text attribute specified the text of the TOC node as it appears in the TOC tree, the target attribute can be either relative URL of the help content file associated with this TOC item (relative to the doc/ directory). It is important that the help file URL is relative to the doc/ directory. We require that at least one of these attributes is defined.
You may use tocitem elements with only the text attribute defined as grouping TOC nodes. If you want to define a TOC node associated with some help content, you must provide the target. If you provide the target only, the text will be generated as the name of the target file, without path and extension.
Here's a sample TOC file:

API

This is a list of modules with bajadoc.

Search

This is a search view to search text.

bajadoc Command

Every module should include reference documentation. Reference documentation is built using the Niagara build tool:

build [moduleDir] bajadoc

The module must already have been built using the build [moduleDir] command. The .bajadoc files are compiled from the Javadoc found in the source code and placed in the "libJar" directory. Then the module is re-jarred using the new .bajadoc files. For more information on building BajaDoc, see build.xml in build.html.

htmldoc Command

htmldoc tool is invoked using the Niagara build tool:

build [moduleDir] htmldoc The module must already have been built using the build [moduleDir] command.

This tool enhances HTML files. Every HTML file will be enhanced with the following:

• style sheet link - This is hard-coded and not configurable. If your HTML file already has a link element in document's head section, the auto-generated link will not be inserted.
• copyright notice - The copyright notice generated is controlled by a property in devkit.properties: htmldoc.copyright=Copyright © 2000-%year% Tridium Inc. All rights reserved. If your document has

  tag, empty or not, the auto-generated copyright notice will not be inserted in it.

• navigation links - Based on the information in the index.html file, navigation links are inserted in every HTML file that doesn't have

  or

  tag. The navigation links include three links:

  • Index - always points to index.html
  • Prev - points to the previous file in TOC, or disabled if this is the first file in TOC, or if this file is not listed in TOC.
  • Next - points to the next file in TOC, or disables if this is the last file in TOC, or if this file is not listed in TOC.

The entire module is then re-jarred, and the enhanced help content is included in the JAR produced.

index Command

Index tool is invoked using the Niagara build tool:

build [moduleDir] index The module must already have been built using the build [moduleDir] command.

Building search indices out of help content.
If you want the .bajadoc documentation to also be indexed, you should run the bajadoc command before running the index command.
During this step, all visible text inside the help content files will be broken into word tokens and stored in the binary files documents.dat, postings.dat, worddocs.dat and words.dat. The entire module is then re-jarred, and the enhanced help content is included in the JAR produced.

Copyright © 2000-2005 Tridium Inc. All rights reserved.