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

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: 
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>
        !            14: 
1.1       whiteley   15: <h4>Overview</h4>
                     16: <p>
                     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.
                     20: </p>
                     21: 
                     22: <p>
                     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.
                     25: </p>
                     26: 
                     27: <p>
                     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.
                     32: </p>
                     33: 
                     34: <p>
                     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.
                     39: </p>
                     40: 
                     41: <p>
                     42: For information about how to install and use BuildHelp, see
                     43: <a href="build.html">Build</a> on this site.
                     44: </p>
                     45: 
                     46: 
                     47: <h5>What BuildHelp does</h5>
                     48: <p>
                     49: BuildHelp automates the building of indexes, jars and XPI installers for
                     50: help content packs.
                     51: </p>
                     52: 
                     53: <p>
                     54: For each locale, it creates:
                     55: <ul>
                     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>
                     61: </ul>
                     62: </p>
                     63: 
                     64: <p>
                     65: It also creates:
                     66: <ul>
                     67: <li><code>context.rdf</code>, the context map</li>
                     68: </ul>
                     69: which applies to all locales.
                     70: </p>
                     71: 
                     72: <p>
                     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.
                     75: </p>
                     76: 
                     77: 
                     78: <h4>Source files for your content pack</h4>
                     79: <p>
                     80: Create a local directory structure for your project similar to
                     81: Calendar Help's directory structure on CVS.
                     82: </p>
                     83: 
                     84: <p>
                     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.
                     88: </p>
                     89: 
                     90: <p>
                     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.
                     95: </p>
                     96: 
                     97: <p>
                     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.
                    103: </p>
                    104: 
                    105: <p>
                    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.
                    109: </p>
                    110: 
                    111: 
                    112: 
                    113: <h5>The glossary</h5>
                    114: <p>
                    115: The source file for the glossary is <code>glossary.xhtml</code> in
                    116: each locale.
                    117: </p>
                    118: 
                    119: <p>
                    120: BuildHelp builds <code>glosary.rdf</code> in each locale.
                    121: </p>
                    122: 
                    123: 
                    124: <h5>The main index</h5>
                    125: <p>
                    126: The source files for the main index are all the <code>.xhtml</code> files in
                    127: each locale.
                    128: </p>
                    129: 
                    130: <p>
                    131: BuildHelp builds <code>index.rdf</code> in each locale.
                    132: </p>
                    133: 
                    134: <p>
                    135: BuildHelp does not include a complete alphabet in the index&mdash;only
                    136: the letters that are actually used.
                    137: </p>
                    138: 
                    139: 
                    140: 
                    141: <h5>The table of contents (ToC)</h5>
                    142: <p>
                    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.
                    145: </p>
                    146: 
                    147: <p>
                    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>.
                    152: </p>
                    153: 
                    154: <p>
                    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>
                    157: tags.
                    158: </p>
                    159: 
                    160: <p>
                    161: There is no need to package <code>files.rdf</code> for installation.
                    162: It is not used at run time.
                    163: </p>
                    164: 
                    165: 
                    166: <h5>The context map</h5>
                    167: <p>
                    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.
                    171: </p>
                    172: 
                    173: <p>
                    174: BuildHelp builds <code>context.rdf</code> in the
                    175: <code><i>projectname</i>/content/<i>projectname</i></code> directory.
                    176: </p>
                    177: 
                    178: <p>
                    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.
                    184: </p>
                    185: 
                    186: <p>
                    187: The JavaScript code that reads the map is in Calendar Help's
                    188: <code>context.js</code>.
                    189: To adapt this file for your own project, you only have to
                    190: change the project name throughout.
                    191: </p>
                    192: 
                    193: 
                    194: <h4>Run-time features</h4>
                    195: <p>
                    196: Calendar Help has some run-time features that you can use in your own help content pack.
                    197: These features provide support for:
                    198: <ul>
                    199: <li>Platform-specific content</li>
                    200: <li>Product-specific content</li>
                    201: <li>Standard HTML entities</li>
                    202: </ul>
                    203: </p>
                    204: 
                    205: <p>
                    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.
                    210: </p>
                    211: 
                    212: 
                    213: <h5>Platform-specific content</h5>
                    214: <p>
                    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.
                    220: </p>
                    221: 
                    222: <p>
                    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.
                    228: </p>
                    229: 
                    230: <p>
                    231: To make this work, load the code from every source file by including:
                    232: <blockquote><pre>
                    233: &lt;script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/&gt;
                    234: </pre></blockquote>
                    235: inside the <code>&lt;head&gt;</code> tag.
                    236: </p>
                    237: 
                    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.
                    244: </p>
                    245: 
                    246: 
                    247: 
                    248: <h5>Product-specific content</h5>
                    249: <p>
                    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.
                    254: </p>
                    255: 
                    256: <p>
                    257: To make this work, there are four things to customize:
                    258: <ol>
                    259: <li>
                    260: The file <code>help.dtd</code> in each locale contains all the translated strings
                    261: for this mechanism.
                    262: </li>
                    263: <li>
                    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>
                    267: <li>
1.2       whiteley  268: Each source file loads <code>parent.dtd</code>.
1.1       whiteley  269: </li>
                    270: <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.
                    273: </li>
                    274: </ol>
                    275: </p>
                    276: 
                    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>
                    282: 
                    283: <h5>Standard HTML entities</h5>
                    284: <p>
                    285: BuildHelp supports HTML entities in entries in the glossary, index and ToC.
                    286: This allows writers to code, for example, e-acute (&eacute;) as <code>&amp;eacute;</code>
                    287: instead of <code>&amp;#233;</code> or the UTF-8 equivalent (<code>&Atilde;&copy;</code>).
                    288: </p>
                    289: 
                    290: <p>
                    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.
                    294: </p>
                    295: 
                    296: 
                    297: 
                    298: <h4 id="options">Options</h4>
                    299: <p>
                    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.
                    305: </p>
                    306: 
                    307: 
                    308: <p>
                    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.
                    316: </p>

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