mozdev.org

CalendarHelp

resources:
developer:
project:
projects:

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

Note: Parts of BuildHelp might be specially coded in a way that only works in Calendar Help. The general intention is to allow BuildHelp to be used with other projects, but if your project's requirements differ from Calendar Help's requirements, then you might have to modify BuildHelp's code.

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 other projects, especially if they contain help content packs.

This page contains information about how to set up the source files for your project and 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. It can also build content for an experimental online viewer.

BuildHelp supports translated content in more than one locale. On this page, the locale xx-XX means the locale that you are currently building.

For each locale, BuildHelp creates:

It also creates one file that applies to all locales:

In addition, BuildHelp can copy project source files from a sandbox (or developement directory) to a CVS directory, adding license information to the files.

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. This local directory structure is your CVS area.

If you wish to develop your project in a sandbox area, create a second similar local directory structure. A sandbox area allows you to make experimental changes to source files without affectng files that are under CVS control. The files in a sandbox area are private to you, so they do not contain license information.

One way to create a local directory structure 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, and that is the base locale shown on this page. 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 source files for each locale are in the text directory, in a subdirectory for the locale. Other translatable files are in the locale directory, in a subdirectory for the locale.

The glossary

The source file for the glossary is text/xx-XX/glossary.xhtml.

BuildHelp builds locale/xx-XX/glosary.rdf, using build/build.properties to supply the DTDs.

The main index

The source files for the main index are all the text/xx-XX/*.xhtml files.

BuildHelp builds locale/xx-XX/index.rdf, using build/build.properties to supply the DTDs.

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, locale/en-US/files.rdf, lists the source files for the ToC. It exists only in the base locale, because it has no translatable content.

Create locale/en-US/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 locale/xx-XX/toc.rdf, using build/build.properties to supply the DTDs. It builds entries only from h1, h2, h3 and h4 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 text/en-US/*.xhtml files for 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 must change the project name throughout and remove or rewrite some code that is specific to Calendar.

The jar file

To create a jar file for the content pack, BuildHelp first converts the source files text/xx-XX/*.xhtml to a form that the help viewer can use, writing the converted files to locale/xx-XX/*.xhtml. It uses build/build.properties to supply the DTDs and the tags in the head. It removes <context> and <index> tags, which are not needed at run time, and applies some additional filters. It adds the tiny license specified in build/build.properties.

This conversion only runs on source files that have changed.

Then BuildHelp runs an external script to create the jar file. The default script is build/ZIP.BAT.

The resulting jar file is install/xx-XX/chrome/projectname-xx_XX.jar

The XPI

To create an installable XPI for the content pack, BuildHelp first converts the installation files install/install.js and install/install.rdf for the locale by adding translated strings from locale/xx-XX/install.properties. It writes the converted files to install/xx-XX/install.*.

Then BuildHelp runs an external script to create the xpi file. The default script is build/ZIP.BAT.

The resulting XPI is install/xx-XX/projectname-v.v-xx_XX.xpi where v.v is the version number.

Online content (experimental)

Note: This is work in progress. Currently, some features of the online content only work in English.

To create online content, BuildHelp first converts the source files text/xx-XX/*.xhtml to a form that the online viewer can use, writing the converted files to www/xx-XX/*.xhtml. It removes <context> and <index> tags, which are not needed at run time, and applies some additional filters. This conversion only runs on source files that have changed.

It also converts the indexes locale/xx-XX/*.rdf, writing the converted files to www/xx-XX/*.rdf.

It uses translated strings from locale/xx-XX/help.dtd.

Update CVS from sandbox

If you develop your project in a sandbox area, BuildHelp can copy source files from there to your CVS area, adding license information to the files. BuildHelp only copies files that have changed.

build/build.properties supplies data for the update, specifying a list of source and target directories, a list of file names to hold back, and the text of the full license added. For an example of the format, see Calendar Help's build/build.properties file.

BuildHelp does not commit changes to CVS. Use a CVS client for this step.

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 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 parent.dtd if necessary.
  3. Each source file loads parent.dtd.
  4. Each index built by BuildHelp loads parent.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.
(2) An obsolete CSS mechanism for this has been 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 html.dtd from the DTDs that BuildHelp includes. See the section Options below for details.

Project information and options

BuildHelp reads project information from a file buildhelp.ini in Firefox's res directory. For example, the file can contain settings like these, corresponding to fields in the user interface:

proj.1=calendarhelp
proj.1.version=0.1
proj.1.base=F:\\Projects
proj.1.subdir=false

To specify second and subsequent projects, add setings for proj.2, etc.

Some other BuildHelp options can be set. 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.

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.

The calendarhelp project can be contacted through the mailing list or the member list.
Copyright © 2000-2017. All rights reserved. Terms of Use & Privacy Policy.