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

version 1.3, 2005/04/28 10:48:56 version 1.4, 2005/04/29 08:41:05
Line 5  This page is a guide to building help fo Line 5  This page is a guide to building help fo
 using Calendar Help's BuildHelp tool.  using Calendar Help's BuildHelp tool.
 </p>  </p>
   
 <p style="border:1px solid red;">  
 <i>  
 Changes to the builder have made this page out of date.  
 It will be updated by end April 2005 to reflect the new features.  
 </i>  
 </p>  
   
 <h4>Overview</h4>  <h4>Overview</h4>
 <p>  <p>
 The BuildHelp tool is part of the Calendar Help project.  The BuildHelp tool is part of the Calendar Help project.
Line 48  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>
   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>
   
 <p>  <p>
For each locale, it creates: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 89  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 108  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 140  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 163  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 184  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>
 
 
 
 
 <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>
   
   <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>
Line 213  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 239  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>
   
   

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


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