Annotation of calendarhelp/www/buildguide.html, revision 1.3
1.1 whiteley 1: <h5 class="page-header">Building help for other projects</h5>
4: This page is a guide to building help for other projects
5: using Calendar Help's BuildHelp tool.
1.3 ! whiteley 8: <p style="border:1px solid red;">
! 9: <i>
! 10: Changes to the builder have made this page out of date.
! 11: It will be updated by end April 2005 to reflect the new features.
! 12: </i>
! 13: </p>
1.1 whiteley 15: <h4>Overview</h4>
17: The BuildHelp tool is part of the Calendar Help project.
18: It is designed to build the help for Calendar and Sunbird.
19: But you can use BuildHelp to build help content packs for other projects.
23: This page contains information about how to set up the source files
24: for your help content pack so that you can use it with BuildHelp.
28: For basic information about help content packs, see:
29: <a href="">Content Packs</a>.
30: Pay no attention to the details of the RDF files described there,
31: because BuildHelp builds these RDF files for you automatically.
35: For information about how to write help source files suitable for
36: BuildHelp, see the
37: <a href="write.html">Guidelines for writers</a> and
38: <a href="translate.html">Guidelines for translators</a> on this site.
42: For information about how to install and use BuildHelp, see
43: <a href="build.html">Build</a> on this site.
47: <h5>What BuildHelp does</h5>
49: BuildHelp automates the building of indexes, jars and XPI installers for
50: help content packs.
54: For each locale, it creates:
56: <li><code>glossary.rdf</code>, the glossary index</li>
57: <li><code>index.rdf</code>, the main index</li>
58: <li><code>toc.rdf</code>, the table of contents</li>
59: <li>a <code>.jar</code> file containing the content pack</li>
60: <li>a XPI installer</li>
65: It also creates:
67: <li><code>context.rdf</code>, the context map</li>
69: which applies to all locales.
73: You can choose which parts of BuildHelp are appropriate for your project.
74: For example, if you do not want a context map, you do not have to build it.
78: <h4>Source files for your content pack</h4>
80: Create a local directory structure for your project similar to
81: Calendar Help's directory structure on CVS.
85: One way to do this is to check out Calendar Help's source files
86: from CVS, then rename the directories and change the files as required
87: for your project.
91: BuildHelp treats one locale as the <i>base locale</i>.
92: By default the base locale is en-US.
93: For information on how to change it, see the section
94: <a href="#options">Options</a> below.
98: Your content pack has a master file in each locale that defines the names
99: of certain parts of the content.
100: But BuildHelp ignores your master file and uses names that are hard coded.
101: So, to use BuildHelp you must make the names in your master file match
102: the names that BuildHelp uses.
106: One way to do this is to use Calendar Help's <code>help.rdf</code>
107: as the basis for your project's master file, changing only those
108: things that you really need to change.
113: <h5>The glossary</h5>
115: The source file for the glossary is <code>glossary.xhtml</code> in
116: each locale.
120: BuildHelp builds <code>glosary.rdf</code> in each locale.
124: <h5>The main index</h5>
126: The source files for the main index are all the <code>.xhtml</code> files in
127: each locale.
131: BuildHelp builds <code>index.rdf</code> in each locale.
135: BuildHelp does not include a complete alphabet in the index—only
136: the letters that are actually used.
141: <h5>The table of contents (ToC)</h5>
143: A special file, <code>files.rdf</code>, lists the source files for the ToC.
144: It exists only in the base locale, because it has no translatable content.
148: Create <code>files.rdf</code> manually, listing all the <code>.xhtml</code> files
149: that you want to include in the ToC, in the sequence that you require.
150: Normally, you include all the source files except the glossary.
151: Copy the format of Calendar Help's <code>files.rdf</code>.
155: BuildHelp builds <code>toc.rdf</code> in each locale.
156: It builds entries only from <code>h1</code>, <code>h2</code> and <code>h3</code>
161: There is no need to package <code>files.rdf</code> for installation.
162: It is not used at run time.
166: <h5>The context map</h5>
168: The source files for the context map are all the <code>.xhtml</code> files in
169: the base locale.
170: The context map has no translatable content.
174: BuildHelp builds <code>context.rdf</code> in the
175: <code><i>projectname</i>/content/<i>projectname</i></code> directory.
179: To make the context map work, you must activate the F1 or Help key in every window
180: of the product that you are writing help for.
181: If you own the product, then you can do this directly.
182: Otherwise you must do it using overlays.
183: For example, see Calendar Help's <code>dialogOverlay.xul</code> file.
189: To adapt this file for your own project, you only have to
190: change the project name throughout.
194: <h4>Run-time features</h4>
196: Calendar Help has some run-time features that you can use in your own help content pack.
197: These features provide support for:
199: <li>Platform-specific content</li>
200: <li>Product-specific content</li>
201: <li>Standard HTML entities</li>
206: You could implement some of these features by running separate builds and
207: providing separate installers.
208: By implementing them at run time, BuildHelp reduces the number of installers
209: that you have to build.
213: <h5>Platform-specific content</h5>
215: A CSS mechanism supports platform-specific content.
216: It can hide or reveal sections of the source text depending on the
217: run-time platform,
218: and it can display platform-specific text defined as content for
219: style classes.
223: The file <code>helpContent.js</code> provides this mechanism by
224: determining the run-time platform and loading the appropriate
225: style sheet: <code>unix.css</code>, <code>mac.css</code> or <code>win.css</code>.
226: These style sheets exist in each locale, because they may contain
227: translatable strings.
231: To make this work, load the code from every source file by including:
235: inside the <code><head></code> tag.
238: <p><strong>Note: </strong>
239: This feature does not work in the ToC, main index or gloassary index,
240: because it uses CSS.
241: A similar feature has been prototyped for the ToC, main index and gloassary index,
242: but it requires a significant change to the help viewer so it has not been implemented
243: in Calendar Help.
248: <h5>Product-specific content</h5>
250: A DTD mechanism supports product-specific content for help content packs that are
251: written for extensions.
252: It can change certain words or phrases depending on the base product that the extenion is
253: installed into.
257: To make this work, there are four things to customize:
260: The file <code>help.dtd</code> in each locale contains all the translated strings
261: for this mechanism.
264: The file <code>context.js</code> determines the base product and locale at run time.
1.2 whiteley 265: It writes <code>parent.dtd</code> if necessary.
1.1 whiteley 266: </li>
1.2 whiteley 268: Each source file loads <code>parent.dtd</code>.
1.1 whiteley 269: </li>
1.2 whiteley 271: Each index built by BuildHelp loads <code>parent.dtd</code>.
1.1 whiteley 272: See the section <a href="#options">Options</a> below for details.
277: <p><strong>Notes: </strong><br>
278: (1) Part of this mechanism is specific to Calendar Help.
1.2 whiteley 279: Customizing it for other projects may require some difficult coding.
280: (2) An obsolete CSS mechanism for this has been removed.
1.1 whiteley 281: </p>
283: <h5>Standard HTML entities</h5>
285: BuildHelp supports HTML entities in entries in the glossary, index and ToC.
286: This allows writers to code, for example, e-acute (é) as <code>&eacute;</code>
287: instead of <code>&#233;</code> or the UTF-8 equivalent (<code>Ã©</code>).
291: If you do not need this, you can remove <code>xhtml11.dtd</code> from the
292: DTDs that BuildHelp includes.
293: See the section <a href="#options">Options</a> below for details.
298: <h4 id="options">Options</h4>
300: Some BuildHelp options can be set without modifying the program code.
301: To work with these options, open the URL <code>about:config</code> in
302: Firefox and filter on <code>buildhelp</code>.
303: Alternatively, close Firefox and edit the <code>prefs.js</code> file
304: in your profile directory.
309: To build jars and XPIs, BuildHelp uses a shell script.
310: By default the shell is <code>COMMAND.COM</code> and
311: the script is <code>ZIP.BAT</code>.
312: If your Windows system does not have <code>COMMAND.COM</code>,
313: you might be able to use <code>CMD.EXE</code>.
314: Or you might be able to use a different shell program and a
315: different script.