File:  [mozdev] / calendarhelp / www / buildguide.html
Revision 1.6: download - view: text, annotated - select for diffs - revision graph
Mon May 23 13:13:09 2005 UTC (12 years, 5 months ago) by whiteley
Branches: MAIN
CVS tags: HEAD
add license info

<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>

<p><strong>Note: </strong>
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.
</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 other projects,
especially if they contain help content packs.
</p>

<p>
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.
</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.
It can also build content for an experimental online viewer.
</p>

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

<p>
For each locale, BuildHelp 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>
<li>online content (experimental)</li>
</ul>
</p>

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

<p>
In addition, BuildHelp can copy project source files from a sandbox (or developement directory)
to a CVS directory, adding license information to the files.
</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.
This local directory structure is your CVS area.
</p>

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

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

<p>
BuildHelp treats one locale as the <i>base locale</i>.
By default the base locale is <code>en-US</code>,
and that is the base locale shown on this page.
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>

<p>
The source files for each locale are in the <code>text</code> directory,
in a subdirectory for the locale.
Other translatable files are in the <code>locale</code> directory,
in a subdirectory for the locale.
</p>



<h5>The glossary</h5>
<p>
The source file for the glossary is <code>text/xx-XX/glossary.xhtml</code>.
</p>

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


<h5>The main index</h5>
<p>
The source files for the main index are all the <code>text/xx-XX/*.xhtml</code> files.
</p>

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




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

This conversion only runs on source files that have changed.
</p>

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

<p>
The resulting jar file is <code>install/xx-XX/chrome/projectname-xx_XX.jar</code>
</p>



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

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

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


<h5>Online content (experimental)</h5>
<p><strong>Note: </strong>
This is work in progress.
Currently, some features of the online content only work in English.
</p>

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

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

<p>
It uses translated strings from <code>locale/xx-XX/help.dtd</code>.
</p>



<h5>Update CVS from sandbox</h5>
<p>
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.
</p>

<p>
<code>build/build.properties</code> 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 <code>build/build.properties</code> file.
</p>

<p>
BuildHelp does not commit changes to CVS.
Use a CVS client for this step.
</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>
</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 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>parent.dtd</code> if necessary.
</li>
<li>
Each source file loads <code>parent.dtd</code>.
</li>
<li>
Each index built by BuildHelp loads <code>parent.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.
<br>
(2) An obsolete CSS mechanism for this has been 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>html.dtd</code> from the
DTDs that BuildHelp includes.
See the section <a href="#options">Options</a> below for details.
</p>



<h4 id="options">Project information and options</h4>
<p>
BuildHelp reads project information from a file <code>buildhelp.ini</code>
in Firefox's <code>res</code> directory.
For example, the file can contain settings like these,
corresponding to fields in the user interface:
<pre>
proj.1=calendarhelp
proj.1.version=0.1
proj.1.base=F:\\Projects
proj.1.subdir=false
</pre>
</p>

<p>
To specify second and subsequent projects, add setings for <code>proj.2</code>, <i>etc</i>.
</p>

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