File:  [mozdev] / calendarhelp / www / buildguide.html
Revision 1.1: download - view: text, annotated - select for diffs - revision graph
Tue Nov 2 12:26:27 2004 UTC (14 years, 11 months ago) by whiteley
Branches: MAIN
CVS tags: HEAD
various web site updates

<h5 class="page-header">Building help for other projects</h5>

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

<h4>Overview</h4>
<p>
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.
</p>

<p>
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.
</p>

<p>
For basic information about help content packs, see:
<a href="">Content Packs</a>.
Pay no attention to the details of the RDF files described there,
because BuildHelp builds these RDF files for you automatically.
</p>

<p>
For information about how to write help source files suitable for
BuildHelp, see the
<a href="write.html">Guidelines for writers</a> and
<a href="translate.html">Guidelines for translators</a> on this site.
</p>

<p>
For information about how to install and use BuildHelp, see
<a href="build.html">Build</a> on this site.
</p>


<h5>What BuildHelp does</h5>
<p>
BuildHelp automates the building of indexes, jars and XPI installers for
help content packs.
</p>

<p>
For each locale, it creates:
<ul>
<li><code>glossary.rdf</code>, the glossary index</li>
<li><code>index.rdf</code>, the main index</li>
<li><code>toc.rdf</code>, the table of contents</li>
<li>a <code>.jar</code> file containing the content pack</li>
<li>a XPI installer</li>
</ul>
</p>

<p>
It also creates:
<ul>
<li><code>context.rdf</code>, the context map</li>
</ul>
which applies to all locales.
</p>

<p>
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.
</p>


<h4>Source files for your content pack</h4>
<p>
Create a local directory structure for your project similar to
Calendar Help's directory structure on CVS.
</p>

<p>
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.
</p>

<p>
BuildHelp treats one locale as the <i>base locale</i>.
By default the base locale is en-US.
For information on how to change it, see the section
<a href="#options">Options</a> below.
</p>

<p>
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.
</p>

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



<h5>The glossary</h5>
<p>
The source file for the glossary is <code>glossary.xhtml</code> in
each locale.
</p>

<p>
BuildHelp builds <code>glosary.rdf</code> in each locale.
</p>


<h5>The main index</h5>
<p>
The source files for the main index are all the <code>.xhtml</code> files in
each locale.
</p>

<p>
BuildHelp builds <code>index.rdf</code> in each locale.
</p>

<p>
BuildHelp does not include a complete alphabet in the index&mdash;only
the letters that are actually used.
</p>



<h5>The table of contents (ToC)</h5>
<p>
A special file, <code>files.rdf</code>, lists the source files for the ToC.
It exists only in the base locale, because it has no translatable content.
</p>

<p>
Create <code>files.rdf</code> manually, listing all the <code>.xhtml</code> 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 <code>files.rdf</code>.
</p>

<p>
BuildHelp builds <code>toc.rdf</code> in each locale.
It builds entries only from <code>h1</code>, <code>h2</code> and <code>h3</code>
tags.
</p>

<p>
There is no need to package <code>files.rdf</code> for installation.
It is not used at run time.
</p>


<h5>The context map</h5>
<p>
The source files for the context map are all the <code>.xhtml</code> files in
the base locale.
The context map has no translatable content.
</p>

<p>
BuildHelp builds <code>context.rdf</code> in the
<code><i>projectname</i>/content/<i>projectname</i></code> directory.
</p>

<p>
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 <code>dialogOverlay.xul</code> file.
</p>

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


<h4>Run-time features</h4>
<p>
Calendar Help has some run-time features that you can use in your own help content pack.
These features provide support for:
<ul>
<li>Platform-specific content</li>
<li>Product-specific content</li>
<li>Standard HTML entities</li>
<li>Product name entities</li>
</ul>
</p>

<p>
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.
</p>


<h5>Platform-specific content</h5>
<p>
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.
</p>

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

<p>
To make this work, load the code from every source file by including:
<blockquote><pre>
&lt;script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/&gt;
</pre></blockquote>
inside the <code>&lt;head&gt;</code> tag.
</p>

<p><strong>Note: </strong>
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.
</p>



<h5>Product-specific content</h5>
<p>
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.
</p>

<p>
To make this work, there are four things to customize:
<ol>
<li>
The file <code>help.dtd</code> in each locale contains all the translated strings
for this mechanism.
</li>
<li>
The file <code>context.js</code> determines the base product and locale at run time.
It writes <code><i>projectname</i>.dtd</code> if necessary.
</li>
<li>
Each source file loads <code><i>projectname</i>.dtd</code>.
</li>
<li>
Each index built by BuildHelp loads <code><i>projectname</i>.dtd</code>.
See the section <a href="#options">Options</a> below for details.
</li>
</ol>
</p>

<p><strong>Notes: </strong><br>
(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.<br>
(2) A CSS mechanism for this still exists, but is deprecated.
It does not work in the ToC or index.
It will be removed.
</p>

<h5>Standard HTML entities</h5>
<p>
BuildHelp supports HTML entities in entries in the glossary, index and ToC.
This allows writers to code, for example, e-acute (&eacute;) as <code>&amp;eacute;</code>
instead of <code>&amp;#233;</code> or the UTF-8 equivalent (<code>&Atilde;&copy;</code>).
</p>

<p>
If you do not need this, you can remove <code>xhtml11.dtd</code> from the
DTDs that BuildHelp includes.
See the section <a href="#options">Options</a> below for details.
</p>


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

<p>
If you do not need this, you can remove <code>brand.dtd</code> from the
DTDs that BuildHelp includes.
See the section <a href="#options">Options</a> below for details.
</p>



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

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

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

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>