Annotation of calendarhelp/www/buildguide.html, revision 1.2

1.1       whiteley    1: <h5 class="page-header">Building help for other projects</h5>
                      2: 
                      3: <p>
                      4: This page is a guide to building help for other projects
                      5: using Calendar Help's BuildHelp tool.
                      6: </p>
                      7: 
                      8: <h4>Overview</h4>
                      9: <p>
                     10: The BuildHelp tool is part of the Calendar Help project.
                     11: It is designed to build the help for Calendar and Sunbird.
                     12: But you can use BuildHelp to build help content packs for other projects.
                     13: </p>
                     14: 
                     15: <p>
                     16: This page contains information about how to set up the source files
                     17: for your help content pack so that you can use it with BuildHelp.
                     18: </p>
                     19: 
                     20: <p>
                     21: For basic information about help content packs, see:
                     22: <a href="">Content Packs</a>.
                     23: Pay no attention to the details of the RDF files described there,
                     24: because BuildHelp builds these RDF files for you automatically.
                     25: </p>
                     26: 
                     27: <p>
                     28: For information about how to write help source files suitable for
                     29: BuildHelp, see the
                     30: <a href="write.html">Guidelines for writers</a> and
                     31: <a href="translate.html">Guidelines for translators</a> on this site.
                     32: </p>
                     33: 
                     34: <p>
                     35: For information about how to install and use BuildHelp, see
                     36: <a href="build.html">Build</a> on this site.
                     37: </p>
                     38: 
                     39: 
                     40: <h5>What BuildHelp does</h5>
                     41: <p>
                     42: BuildHelp automates the building of indexes, jars and XPI installers for
                     43: help content packs.
                     44: </p>
                     45: 
                     46: <p>
                     47: For each locale, it creates:
                     48: <ul>
                     49: <li><code>glossary.rdf</code>, the glossary index</li>
                     50: <li><code>index.rdf</code>, the main index</li>
                     51: <li><code>toc.rdf</code>, the table of contents</li>
                     52: <li>a <code>.jar</code> file containing the content pack</li>
                     53: <li>a XPI installer</li>
                     54: </ul>
                     55: </p>
                     56: 
                     57: <p>
                     58: It also creates:
                     59: <ul>
                     60: <li><code>context.rdf</code>, the context map</li>
                     61: </ul>
                     62: which applies to all locales.
                     63: </p>
                     64: 
                     65: <p>
                     66: You can choose which parts of BuildHelp are appropriate for your project.
                     67: For example, if you do not want a context map, you do not have to build it.
                     68: </p>
                     69: 
                     70: 
                     71: <h4>Source files for your content pack</h4>
                     72: <p>
                     73: Create a local directory structure for your project similar to
                     74: Calendar Help's directory structure on CVS.
                     75: </p>
                     76: 
                     77: <p>
                     78: One way to do this is to check out Calendar Help's source files
                     79: from CVS, then rename the directories and change the files as required
                     80: for your project.
                     81: </p>
                     82: 
                     83: <p>
                     84: BuildHelp treats one locale as the <i>base locale</i>.
                     85: By default the base locale is en-US.
                     86: For information on how to change it, see the section
                     87: <a href="#options">Options</a> below.
                     88: </p>
                     89: 
                     90: <p>
                     91: Your content pack has a master file in each locale that defines the names
                     92: of certain parts of the content.
                     93: But BuildHelp ignores your master file and uses names that are hard coded.
                     94: So, to use BuildHelp you must make the names in your master file match
                     95: the names that BuildHelp uses.
                     96: </p>
                     97: 
                     98: <p>
                     99: One way to do this is to use Calendar Help's <code>help.rdf</code>
                    100: as the basis for your project's master file, changing only those
                    101: things that you really need to change.
                    102: </p>
                    103: 
                    104: 
                    105: 
                    106: <h5>The glossary</h5>
                    107: <p>
                    108: The source file for the glossary is <code>glossary.xhtml</code> in
                    109: each locale.
                    110: </p>
                    111: 
                    112: <p>
                    113: BuildHelp builds <code>glosary.rdf</code> in each locale.
                    114: </p>
                    115: 
                    116: 
                    117: <h5>The main index</h5>
                    118: <p>
                    119: The source files for the main index are all the <code>.xhtml</code> files in
                    120: each locale.
                    121: </p>
                    122: 
                    123: <p>
                    124: BuildHelp builds <code>index.rdf</code> in each locale.
                    125: </p>
                    126: 
                    127: <p>
                    128: BuildHelp does not include a complete alphabet in the index&mdash;only
                    129: the letters that are actually used.
                    130: </p>
                    131: 
                    132: 
                    133: 
                    134: <h5>The table of contents (ToC)</h5>
                    135: <p>
                    136: A special file, <code>files.rdf</code>, lists the source files for the ToC.
                    137: It exists only in the base locale, because it has no translatable content.
                    138: </p>
                    139: 
                    140: <p>
                    141: Create <code>files.rdf</code> manually, listing all the <code>.xhtml</code> files
                    142: that you want to include in the ToC, in the sequence that you require.
                    143: Normally, you include all the source files except the glossary.
                    144: Copy the format of Calendar Help's <code>files.rdf</code>.
                    145: </p>
                    146: 
                    147: <p>
                    148: BuildHelp builds <code>toc.rdf</code> in each locale.
                    149: It builds entries only from <code>h1</code>, <code>h2</code> and <code>h3</code>
                    150: tags.
                    151: </p>
                    152: 
                    153: <p>
                    154: There is no need to package <code>files.rdf</code> for installation.
                    155: It is not used at run time.
                    156: </p>
                    157: 
                    158: 
                    159: <h5>The context map</h5>
                    160: <p>
                    161: The source files for the context map are all the <code>.xhtml</code> files in
                    162: the base locale.
                    163: The context map has no translatable content.
                    164: </p>
                    165: 
                    166: <p>
                    167: BuildHelp builds <code>context.rdf</code> in the
                    168: <code><i>projectname</i>/content/<i>projectname</i></code> directory.
                    169: </p>
                    170: 
                    171: <p>
                    172: To make the context map work, you must activate the F1 or Help key in every window
                    173: of the product that you are writing help for.
                    174: If you own the product, then you can do this directly.
                    175: Otherwise you must do it using overlays.
                    176: For example, see Calendar Help's <code>dialogOverlay.xul</code> file.
                    177: </p>
                    178: 
                    179: <p>
                    180: The JavaScript code that reads the map is in Calendar Help's
                    181: <code>context.js</code>.
                    182: To adapt this file for your own project, you only have to
                    183: change the project name throughout.
                    184: </p>
                    185: 
                    186: 
                    187: <h4>Run-time features</h4>
                    188: <p>
                    189: Calendar Help has some run-time features that you can use in your own help content pack.
                    190: These features provide support for:
                    191: <ul>
                    192: <li>Platform-specific content</li>
                    193: <li>Product-specific content</li>
                    194: <li>Standard HTML entities</li>
                    195: </ul>
                    196: </p>
                    197: 
                    198: <p>
                    199: You could implement some of these features by running separate builds and
                    200: providing separate installers.
                    201: By implementing them at run time, BuildHelp reduces the number of installers
                    202: that you have to build.
                    203: </p>
                    204: 
                    205: 
                    206: <h5>Platform-specific content</h5>
                    207: <p>
                    208: A CSS mechanism supports platform-specific content.
                    209: It can hide or reveal sections of the source text depending on the
                    210: run-time platform,
                    211: and it can display platform-specific text defined as content for
                    212: style classes.
                    213: </p>
                    214: 
                    215: <p>
                    216: The file <code>helpContent.js</code> provides this mechanism by
                    217: determining the run-time platform and loading the appropriate
                    218: style sheet: <code>unix.css</code>, <code>mac.css</code> or <code>win.css</code>.
                    219: These style sheets exist in each locale, because they may contain
                    220: translatable strings.
                    221: </p>
                    222: 
                    223: <p>
                    224: To make this work, load the code from every source file by including:
                    225: <blockquote><pre>
                    226: &lt;script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/&gt;
                    227: </pre></blockquote>
                    228: inside the <code>&lt;head&gt;</code> tag.
                    229: </p>
                    230: 
                    231: <p><strong>Note: </strong>
                    232: This feature does not work in the ToC, main index or gloassary index,
                    233: because it uses CSS.
                    234: A similar feature has been prototyped for the ToC, main index and gloassary index,
                    235: but it requires a significant change to the help viewer so it has not been implemented
                    236: in Calendar Help.
                    237: </p>
                    238: 
                    239: 
                    240: 
                    241: <h5>Product-specific content</h5>
                    242: <p>
                    243: A DTD mechanism supports product-specific content for help content packs that are
                    244: written for extensions.
                    245: It can change certain words or phrases depending on the base product that the extenion is
                    246: installed into.
                    247: </p>
                    248: 
                    249: <p>
                    250: To make this work, there are four things to customize:
                    251: <ol>
                    252: <li>
                    253: The file <code>help.dtd</code> in each locale contains all the translated strings
                    254: for this mechanism.
                    255: </li>
                    256: <li>
                    257: The file <code>context.js</code> determines the base product and locale at run time.
1.2     ! whiteley  258: It writes <code>parent.dtd</code> if necessary.
1.1       whiteley  259: </li>
                    260: <li>
1.2     ! whiteley  261: Each source file loads <code>parent.dtd</code>.
1.1       whiteley  262: </li>
                    263: <li>
1.2     ! whiteley  264: Each index built by BuildHelp loads <code>parent.dtd</code>.
1.1       whiteley  265: See the section <a href="#options">Options</a> below for details.
                    266: </li>
                    267: </ol>
                    268: </p>
                    269: 
                    270: <p><strong>Notes: </strong><br>
                    271: (1) Part of this mechanism is specific to Calendar Help.
1.2     ! whiteley  272: Customizing it for other projects may require some difficult coding.
        !           273: (2) An obsolete CSS mechanism for this has been removed.
1.1       whiteley  274: </p>
                    275: 
                    276: <h5>Standard HTML entities</h5>
                    277: <p>
                    278: BuildHelp supports HTML entities in entries in the glossary, index and ToC.
                    279: This allows writers to code, for example, e-acute (&eacute;) as <code>&amp;eacute;</code>
                    280: instead of <code>&amp;#233;</code> or the UTF-8 equivalent (<code>&Atilde;&copy;</code>).
                    281: </p>
                    282: 
                    283: <p>
                    284: If you do not need this, you can remove <code>xhtml11.dtd</code> from the
                    285: DTDs that BuildHelp includes.
                    286: See the section <a href="#options">Options</a> below for details.
                    287: </p>
                    288: 
                    289: 
                    290: 
                    291: <h4 id="options">Options</h4>
                    292: <p>
                    293: Some BuildHelp options can be set without modifying the program code.
                    294: To work with these options, open the URL <code>about:config</code> in
                    295: Firefox and filter on <code>buildhelp</code>.
                    296: Alternatively, close Firefox and edit the <code>prefs.js</code> file
                    297: in your profile directory.
                    298: </p>
                    299: 
                    300: 
                    301: <p>
                    302: To build jars and XPIs, BuildHelp uses a shell script.
                    303: By default the shell is <code>COMMAND.COM</code> and
                    304: the script is <code>ZIP.BAT</code>.
                    305: If your Windows system does not have <code>COMMAND.COM</code>,
                    306: you might be able to use <code>CMD.EXE</code>.
                    307: Or you might be able to use a different shell program and a
                    308: different script.
                    309: </p>

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