Diff for /calendarhelp/www/buildguide.html between versions 1.1 and 1.4

version 1.1, 2004/11/02 12:26:27 version 1.4, 2005/04/29 08:41:05
Line 41  For information about how to install and Line 41  For information about how to install and
 <p>  <p>
 BuildHelp automates the building of indexes, jars and XPI installers for  BuildHelp automates the building of indexes, jars and XPI installers for
 help content packs.  help content packs.
   It can also build content for an experimental online viewer.
 </p>  </p>
   
 <p>  <p>
For each locale, it creates: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>  <ul>
 <li><code>glossary.rdf</code>, the glossary index</li>  <li><code>glossary.rdf</code>, the glossary index</li>
 <li><code>index.rdf</code>, the main index</li>  <li><code>index.rdf</code>, the main index</li>
 <li><code>toc.rdf</code>, the table of contents</li>  <li><code>toc.rdf</code>, the table of contents</li>
 <li>a <code>.jar</code> file containing the content pack</li>  <li>a <code>.jar</code> file containing the content pack</li>
 <li>a XPI installer</li>  <li>a XPI installer</li>
   <li>online content (experimental)</li>
 </ul>  </ul>
 </p>  </p>
   
Line 82  for your project. Line 89  for your project.
   
 <p>  <p>
 BuildHelp treats one locale as the <i>base locale</i>.  BuildHelp treats one locale as the <i>base locale</i>.
By default the base locale is en-US.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  For information on how to change it, see the section
 <a href="#options">Options</a> below.  <a href="#options">Options</a> below.
 </p>  </p>
Line 101  as the basis for your project's master f Line 109  as the basis for your project's master f
 things that you really need to change.  things that you really need to change.
 </p>  </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>  <h5>The glossary</h5>
 <p>  <p>
The source file for the glossary is <code>glossary.xhtml</code> inThe source file for the glossary is <code>text/xx-XX/glossary.xhtml</code>.
each locale. 
 </p>  </p>
   
 <p>  <p>
BuildHelp builds <code>glosary.rdf</code> in each locale.BuildHelp builds <code>locale/xx-XX/glosary.rdf</code>,
 using <code>build/build.properties</code> to supply the DTDs.
 </p>  </p>
   
   
 <h5>The main index</h5>  <h5>The main index</h5>
 <p>  <p>
The source files for the main index are all the <code>.xhtml</code> files inThe source files for the main index are all the <code>text/xx-XX/*.xhtml</code> files.
each locale. 
 </p>  </p>
   
 <p>  <p>
BuildHelp builds <code>index.rdf</code> in each locale.BuildHelp builds <code>locale/xx-XX/index.rdf</code>,
 using <code>build/build.properties</code> to supply the DTDs.
 </p>  </p>
   
 <p>  <p>
Line 133  the letters that are actually used. Line 148  the letters that are actually used.
   
 <h5>The table of contents (ToC)</h5>  <h5>The table of contents (ToC)</h5>
 <p>  <p>
A special file, <code>files.rdf</code>, lists the source files for the ToC.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.  It exists only in the base locale, because it has no translatable content.
 </p>  </p>
   
 <p>  <p>
Create <code>files.rdf</code> manually, listing all the <code>.xhtml</code> filesCreate <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.  that you want to include in the ToC, in the sequence that you require.
 Normally, you include all the source files except the glossary.  Normally, you include all the source files except the glossary.
 Copy the format of Calendar Help's <code>files.rdf</code>.  Copy the format of Calendar Help's <code>files.rdf</code>.
 </p>  </p>
   
 <p>  <p>
BuildHelp builds <code>toc.rdf</code> in each locale.BuildHelp builds <code>locale/xx-XX/toc.rdf</code>,
It builds entries only from <code>h1</code>, <code>h2</code> and <code>h3</code>using <code>build/build.properties</code> to supply the DTDs.
tags.It builds entries only from <code>h1</code>, <code>h2</code>,
 <code>h3</code> and <code>h4</code> tags.
 </p>  </p>
   
 <p>  <p>
Line 156  It is not used at run time. Line 172  It is not used at run time.
 </p>  </p>
   
   
   
 <h5>The context map</h5>  <h5>The context map</h5>
 <p>  <p>
The source files for the context map are all the <code>.xhtml</code> files inThe source files for the context map are all the <code>text/en-US/*.xhtml</code>
the base locale.files for the base locale.
 The context map has no translatable content.  The context map has no translatable content.
 </p>  </p>
   
Line 177  For example, see Calendar Help's <code>d Line 194  For example, see Calendar Help's <code>d
 </p>  </p>
   
 <p>  <p>
The JavaScript code that reads the map is in Calendar Help'sThe JavaScript code that reads the map is in Calendar Help's <code>context.js</code>.
<code>context.js</code>.To adapt this file for your own project, you must change the project name throughout
To adapt this file for your own project, you only have toand remove or rewrite some code that is specific to Calendar.
change the project name throughout. 
 </p>  </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 <context> and <index> tags, which are not needed at run time.
   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 <context> and <index> tags, which are not needed at run time.
   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>
   
   
   
   
   
 <h4>Run-time features</h4>  <h4>Run-time features</h4>
 <p>  <p>
 Calendar Help has some run-time features that you can use in your own help content pack.  Calendar Help has some run-time features that you can use in your own help content pack.
Line 192  These features provide support for: Line 277  These features provide support for:
 <li>Platform-specific content</li>  <li>Platform-specific content</li>
 <li>Product-specific content</li>  <li>Product-specific content</li>
 <li>Standard HTML entities</li>  <li>Standard HTML entities</li>
 <li>Product name entities</li>  
 </ul>  </ul>
 </p>  </p>
   
Line 207  that you have to build. Line 291  that you have to build.
 <h5>Platform-specific content</h5>  <h5>Platform-specific content</h5>
 <p>  <p>
 A CSS mechanism supports platform-specific content.  A CSS mechanism supports platform-specific content.
It can hide or reveal sections of the source text depending on theIt can hide or reveal sections of the text depending on the run-time platform,
run-time platform,and it can display platform-specific text defined as content for style classes.
and it can display platform-specific text defined as content for 
style classes. 
 </p>  </p>
   
 <p>  <p>
 The file <code>helpContent.js</code> provides this mechanism by  The file <code>helpContent.js</code> provides this mechanism by
 determining the run-time platform and loading the appropriate  determining the run-time platform and loading the appropriate
 style sheet: <code>unix.css</code>, <code>mac.css</code> or <code>win.css</code>.  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 containThese style sheets exist in each locale, because they may contain translatable strings.
translatable strings. 
 </p>  </p>
   
 <p>  <p>
Line 233  inside the <code>&lt;head&gt;</code> tag Line 314  inside the <code>&lt;head&gt;</code> tag
 This feature does not work in the ToC, main index or gloassary index,  This feature does not work in the ToC, main index or gloassary index,
 because it uses CSS.  because it uses CSS.
 A similar feature has been prototyped for the ToC, main index and gloassary index,  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 implementedbut it requires a significant change to the help viewer so it has not been implemented in Calendar Help.
in Calendar Help. 
 </p>  </p>
   
   
Line 256  for this mechanism. Line 336  for this mechanism.
 </li>  </li>
 <li>  <li>
 The file <code>context.js</code> determines the base product and locale at run time.  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.It writes <code>parent.dtd</code> if necessary.
 </li>  </li>
 <li>  <li>
Each source file loads <code><i>projectname</i>.dtd</code>.Each source file loads <code>parent.dtd</code>.
 </li>  </li>
 <li>  <li>
Each index built by BuildHelp loads <code><i>projectname</i>.dtd</code>.Each index built by BuildHelp loads <code>parent.dtd</code>.
 See the section <a href="#options">Options</a> below for details.  See the section <a href="#options">Options</a> below for details.
 </li>  </li>
 </ol>  </ol>
Line 270  See the section <a href="#options">Optio Line 350  See the section <a href="#options">Optio
   
 <p><strong>Notes: </strong><br>  <p><strong>Notes: </strong><br>
 (1) Part of this mechanism is specific to Calendar Help.  (1) Part of this mechanism is specific to Calendar Help.
Customizing it for other projects may require some difficult codingCustomizing it for other projects may require some difficult coding.
(at step 2, above) to determine the base product exactly.<br>(2) An obsolete CSS mechanism for this has been removed.
(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>  </p>
   
 <h5>Standard HTML entities</h5>  <h5>Standard HTML entities</h5>
Line 291  See the section <a href="#options">Optio Line 368  See the section <a href="#options">Optio
 </p>  </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>  <h4 id="options">Options</h4>
 <p>  <p>
Line 315  Alternatively, close Firefox and edit th Line 378  Alternatively, close Firefox and edit th
 in your profile directory.  in your profile directory.
 </p>  </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>  <p>
 To build jars and XPIs, BuildHelp uses a shell script.  To build jars and XPIs, BuildHelp uses a shell script.

Removed from v.1.1  
changed lines
  Added in v.1.4


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