This page is a guide to building help for other projects using Calendar Help's BuildHelp tool.

Overview

The BuildHelp tool is part of the Calendar Help project. It is designed to build the help for Calendar and Sunbird. But you can use BuildHelp to build help content packs for other projects.

This page contains information about how to set up the source files for your help content pack so that you can use it with BuildHelp.

For basic information about help content packs, see: Content Packs. Pay no attention to the details of the RDF files described there, because BuildHelp builds these RDF files for you automatically.

For information about how to write help source files suitable for BuildHelp, see the Guidelines for writers and Guidelines for translators on this site.

For information about how to install and use BuildHelp, see Build on this site.

What BuildHelp does

BuildHelp automates the building of indexes, jars and XPI installers for help content packs.

For each locale, it creates:

It also creates:

which applies to all locales.

You can choose which parts of BuildHelp are appropriate for your project. For example, if you do not want a context map, you do not have to build it.

Source files for your content pack

Create a local directory structure for your project similar to Calendar Help's directory structure on CVS.

One way to do this is to check out Calendar Help's source files from CVS, then rename the directories and change the files as required for your project.

BuildHelp treats one locale as the base locale. By default the base locale is en-US. For information on how to change it, see the section Options below.

Your content pack has a master file in each locale that defines the names of certain parts of the content. But BuildHelp ignores your master file and uses names that are hard coded. So, to use BuildHelp you must make the names in your master file match the names that BuildHelp uses.

One way to do this is to use Calendar Help's help.rdf as the basis for your project's master file, changing only those things that you really need to change.

The glossary

The source file for the glossary is glossary.xhtml in each locale.

BuildHelp builds glosary.rdf in each locale.

The main index

The source files for the main index are all the .xhtml files in each locale.

BuildHelp builds index.rdf in each locale.

BuildHelp does not include a complete alphabet in the index—only the letters that are actually used.

The table of contents (ToC)

A special file, files.rdf, lists the source files for the ToC. It exists only in the base locale, because it has no translatable content.

Create files.rdf manually, listing all the .xhtml files that you want to include in the ToC, in the sequence that you require. Normally, you include all the source files except the glossary. Copy the format of Calendar Help's files.rdf.

BuildHelp builds toc.rdf in each locale. It builds entries only from h1, h2 and h3 tags.

There is no need to package files.rdf for installation. It is not used at run time.

The context map

The source files for the context map are all the .xhtml files in the base locale. The context map has no translatable content.

BuildHelp builds context.rdf in the projectname/content/projectname directory.

To make the context map work, you must activate the F1 or Help key in every window of the product that you are writing help for. If you own the product, then you can do this directly. Otherwise you must do it using overlays. For example, see Calendar Help's dialogOverlay.xul file.

The JavaScript code that reads the map is in Calendar Help's context.js. To adapt this file for your own project, you only have to change the project name throughout.

Run-time features

Calendar Help has some run-time features that you can use in your own help content pack. These features provide support for:

You could implement some of these features by running separate builds and providing separate installers. By implementing them at run time, BuildHelp reduces the number of installers that you have to build.

Platform-specific content

A CSS mechanism supports platform-specific content. It can hide or reveal sections of the source text depending on the run-time platform, and it can display platform-specific text defined as content for style classes.

The file helpContent.js provides this mechanism by determining the run-time platform and loading the appropriate style sheet: unix.css, mac.css or win.css. These style sheets exist in each locale, because they may contain translatable strings.

To make this work, load the code from every source file by including:

<script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/>
inside the <head> tag.

Note: This feature does not work in the ToC, main index or gloassary index, because it uses CSS. A similar feature has been prototyped for the ToC, main index and gloassary index, but it requires a significant change to the help viewer so it has not been implemented in Calendar Help.

Product-specific content

A DTD mechanism supports product-specific content for help content packs that are written for extensions. It can change certain words or phrases depending on the base product that the extenion is installed into.

To make this work, there are four things to customize:

  1. The file help.dtd in each locale contains all the translated strings for this mechanism.
  2. The file context.js determines the base product and locale at run time. It writes projectname.dtd if necessary.
  3. Each source file loads projectname.dtd.
  4. Each index built by BuildHelp loads projectname.dtd. See the section Options below for details.

Notes:
(1) Part of this mechanism is specific to Calendar Help. Customizing it for other projects may require some difficult coding (at step 2, above) to determine the base product exactly.
(2) A CSS mechanism for this still exists, but is deprecated. It does not work in the ToC or index. It will be removed.

Standard HTML entities

BuildHelp supports HTML entities in entries in the glossary, index and ToC. This allows writers to code, for example, e-acute (é) as &eacute; instead of &#233; or the UTF-8 equivalent (é).

If you do not need this, you can remove xhtml11.dtd from the DTDs that BuildHelp includes. See the section Options below for details.

Product name entities

BuildHelp supports Mozilla product name entities in entries in the glossary, index and ToC. This allows writers to code, for example, &brandShortName; instead of hard-coding the name of the product.

If you do not need this, you can remove brand.dtd from the DTDs that BuildHelp includes. See the section Options below for details.

Options

Some BuildHelp options can be set without modifying the program code. To work with these options, open the URL about:config in Firefox and filter on buildhelp. Alternatively, close Firefox and edit the prefs.js file in your profile directory.

In the list of DTDs, BuildHelp ignores any empty string. The special DTD file name [projectname] resolves to the actual project name that you specify in BuildHelp's UI.

To build jars and XPIs, BuildHelp uses a shell script. By default the shell is COMMAND.COM and the script is ZIP.BAT. If your Windows system does not have COMMAND.COM, you might be able to use CMD.EXE. Or you might be able to use a different shell program and a different script.