This page is a guide to building help for other projects using Calendar Help's BuildHelp tool.
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.
BuildHelp automates the building of indexes, jars and XPI installers for help content packs.
For each locale, it creates:
glossary.rdf, the glossary index
index.rdf, the main index
toc.rdf, the table of contents
.jarfile containing the content pack
It also creates:
context.rdf, the context map
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.
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
as the basis for your project's master file, changing only those
things that you really need to change.
The source file for the glossary is
glosary.rdf in each locale.
The source files for the main index are all the
.xhtml files in
index.rdf in each locale.
BuildHelp does not include a complete alphabet in the index—only the letters that are actually used.
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.
files.rdf manually, listing all the
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
toc.rdf in each locale.
It builds entries only from
There is no need to package
files.rdf for installation.
It is not used at run time.
The source files for the context map are all the
.xhtml files in
the base locale.
The context map has no translatable content.
context.rdf in the
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
To adapt this file for your own project, you only have to
change the project name throughout.
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.
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.
helpContent.js provides this mechanism by
determining the run-time platform and loading the appropriate
These style sheets exist in each locale, because they may contain
To make this work, load the code from every source file by including:
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.
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:
help.dtdin each locale contains all the translated strings for this mechanism.
context.jsdetermines the base product and locale at run time. It writes
parent.dtd. See the section Options below for details.
(1) Part of this mechanism is specific to Calendar Help. Customizing it for other projects may require some difficult coding. (2) An obsolete CSS mechanism for this has been removed.
BuildHelp supports HTML entities in entries in the glossary, index and ToC.
This allows writers to code, for example, e-acute (é) as
é 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.
Some BuildHelp options can be set without modifying the program code.
To work with these options, open the URL
Firefox and filter on
Alternatively, close Firefox and edit the
in your profile directory.
To build jars and XPIs, BuildHelp uses a shell script.
By default the shell is
the script is
If your Windows system does not have
you might be able to use
Or you might be able to use a different shell program and a