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

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.
1.4       whiteley   44: It can also build content for an experimental online viewer.
                     45: </p>
                     46: 
                     47: <p>
                     48: BuildHelp supports translated content in more than one locale.
                     49: On this page, the locale <code>xx-XX</code> means the locale that you are currently building.
1.1       whiteley   50: </p>
                     51: 
                     52: <p>
1.4       whiteley   53: For each locale, BuildHelp creates:
1.1       whiteley   54: <ul>
                     55: <li><code>glossary.rdf</code>, the glossary index</li>
                     56: <li><code>index.rdf</code>, the main index</li>
                     57: <li><code>toc.rdf</code>, the table of contents</li>
                     58: <li>a <code>.jar</code> file containing the content pack</li>
                     59: <li>a XPI installer</li>
1.4       whiteley   60: <li>online content (experimental)</li>
1.1       whiteley   61: </ul>
                     62: </p>
                     63: 
                     64: <p>
1.5     ! whiteley   65: It also creates one file that applies to all locales:
1.1       whiteley   66: <ul>
                     67: <li><code>context.rdf</code>, the context map</li>
                     68: </ul>
                     69: </p>
                     70: 
                     71: <p>
                     72: You can choose which parts of BuildHelp are appropriate for your project.
                     73: For example, if you do not want a context map, you do not have to build it.
                     74: </p>
                     75: 
                     76: 
                     77: <h4>Source files for your content pack</h4>
                     78: <p>
                     79: Create a local directory structure for your project similar to
                     80: Calendar Help's directory structure on CVS.
                     81: </p>
                     82: 
                     83: <p>
                     84: One way to do this is to check out Calendar Help's source files
                     85: from CVS, then rename the directories and change the files as required
                     86: for your project.
                     87: </p>
                     88: 
                     89: <p>
                     90: BuildHelp treats one locale as the <i>base locale</i>.
1.4       whiteley   91: By default the base locale is <code>en-US</code>,
                     92: and that is the base locale shown on this page.
1.1       whiteley   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: 
1.4       whiteley  111: <p>
                    112: The source files for each locale are in the <code>text</code> directory,
                    113: in a subdirectory for the locale.
                    114: Other translatable files are in the <code>locale</code> directory,
                    115: in a subdirectory for the locale.
                    116: </p>
                    117: 
1.1       whiteley  118: 
                    119: 
                    120: <h5>The glossary</h5>
                    121: <p>
1.4       whiteley  122: The source file for the glossary is <code>text/xx-XX/glossary.xhtml</code>.
1.1       whiteley  123: </p>
                    124: 
                    125: <p>
1.4       whiteley  126: BuildHelp builds <code>locale/xx-XX/glosary.rdf</code>,
                    127: using <code>build/build.properties</code> to supply the DTDs.
1.1       whiteley  128: </p>
                    129: 
                    130: 
                    131: <h5>The main index</h5>
                    132: <p>
1.4       whiteley  133: The source files for the main index are all the <code>text/xx-XX/*.xhtml</code> files.
1.1       whiteley  134: </p>
                    135: 
                    136: <p>
1.4       whiteley  137: BuildHelp builds <code>locale/xx-XX/index.rdf</code>,
                    138: using <code>build/build.properties</code> to supply the DTDs.
1.1       whiteley  139: </p>
                    140: 
                    141: <p>
                    142: BuildHelp does not include a complete alphabet in the index&mdash;only
                    143: the letters that are actually used.
                    144: </p>
                    145: 
                    146: 
                    147: 
                    148: <h5>The table of contents (ToC)</h5>
                    149: <p>
1.4       whiteley  150: A special file, <code>locale/en-US/files.rdf</code>, lists the source files for the ToC.
1.1       whiteley  151: It exists only in the base locale, because it has no translatable content.
                    152: </p>
                    153: 
                    154: <p>
1.4       whiteley  155: Create <code>locale/en-US/files.rdf</code> manually, listing all the <code>.xhtml</code> files
1.1       whiteley  156: that you want to include in the ToC, in the sequence that you require.
                    157: Normally, you include all the source files except the glossary.
                    158: Copy the format of Calendar Help's <code>files.rdf</code>.
                    159: </p>
                    160: 
                    161: <p>
1.4       whiteley  162: BuildHelp builds <code>locale/xx-XX/toc.rdf</code>,
                    163: using <code>build/build.properties</code> to supply the DTDs.
                    164: It builds entries only from <code>h1</code>, <code>h2</code>,
                    165: <code>h3</code> and <code>h4</code> tags.
1.1       whiteley  166: </p>
                    167: 
                    168: <p>
                    169: There is no need to package <code>files.rdf</code> for installation.
                    170: It is not used at run time.
                    171: </p>
                    172: 
                    173: 
1.4       whiteley  174: 
1.1       whiteley  175: <h5>The context map</h5>
                    176: <p>
1.4       whiteley  177: The source files for the context map are all the <code>text/en-US/*.xhtml</code>
                    178: files for the base locale.
1.1       whiteley  179: The context map has no translatable content.
                    180: </p>
                    181: 
                    182: <p>
                    183: BuildHelp builds <code>context.rdf</code> in the
                    184: <code><i>projectname</i>/content/<i>projectname</i></code> directory.
                    185: </p>
                    186: 
                    187: <p>
                    188: To make the context map work, you must activate the F1 or Help key in every window
                    189: of the product that you are writing help for.
                    190: If you own the product, then you can do this directly.
                    191: Otherwise you must do it using overlays.
                    192: For example, see Calendar Help's <code>dialogOverlay.xul</code> file.
                    193: </p>
                    194: 
                    195: <p>
1.4       whiteley  196: The JavaScript code that reads the map is in Calendar Help's <code>context.js</code>.
                    197: To adapt this file for your own project, you must change the project name throughout
                    198: and remove or rewrite some code that is specific to Calendar.
                    199: </p>
                    200: 
                    201: 
                    202: 
                    203: 
                    204: <h5>The jar file</h5>
                    205: <p>
                    206: To create a jar file for the content pack, BuildHelp first converts the source files
                    207: <code>text/xx-XX/*.xhtml</code> to a form that the help viewer can use, writing the
                    208: converted files to <code>locale/xx-XX/*.xhtml</code>.
                    209: It uses <code>build/build.properties</code> to supply the DTDs and the tags in the head.
1.5     ! whiteley  210: It removes <code>&lt;context&gt;</code> and <code>&lt;index&gt;</code> tags, which are not needed at run time.
1.4       whiteley  211: This conversion only runs on source files that have changed.
                    212: </p>
                    213: 
                    214: <p>
                    215: Then BuildHelp runs an external script to create the jar file.
                    216: The default script is <code>build/ZIP.BAT</code>.
                    217: </p>
                    218: 
                    219: <p>
                    220: The resulting jar file is <code>install/xx-XX/chrome/projectname-xx_XX.jar</code>
                    221: </p>
                    222: 
                    223: 
                    224: 
                    225: <h5>The XPI</h5>
                    226: <p>
                    227: To create an installable XPI for the content pack, BuildHelp first converts the
                    228: installation files <code>install/install.js</code> and <code>install/install.rdf</code>
                    229: for the locale by adding translated strings from <code>locale/xx-XX/install.properties</code>.
                    230: It writes the converted files to <code>install/xx-XX/install.*</code>.
                    231: </p>
                    232: 
                    233: <p>
                    234: Then BuildHelp runs an external script to create the xpi file.
                    235: The default script is <code>build/ZIP.BAT</code>.
                    236: </p>
                    237: 
                    238: <p>
                    239: The resulting XPI is <code>install/xx-XX/projectname-v.v-xx_XX.xpi</code>
                    240: where <code>v.v</code> is the version number.
                    241: </p>
                    242: 
                    243: 
                    244: <h5>Online content (experimental)</h5>
                    245: <p><strong>Note: </strong>
                    246: This is work in progress.
                    247: Currently, some features of the online content only work in English.
                    248: </p>
                    249: 
                    250: <p>
                    251: To create online content, BuildHelp first converts the source files
                    252: <code>text/xx-XX/*.xhtml</code> to a form that the online viewer can use, writing the
                    253: converted files to <code>www/xx-XX/*.xhtml</code>.
1.5     ! whiteley  254: It removes <code>&lt;context&gt;</code> and <code>&lt;index&gt;</code> tags, which are not needed at run time.
1.4       whiteley  255: This conversion only runs on source files that have changed.
                    256: </p>
                    257: 
                    258: <p>
                    259: It also converts the indexes <code>locale/xx-XX/*.rdf</code>, writing the
                    260: converted files to <code>www/xx-XX/*.rdf</code>.
1.1       whiteley  261: </p>
                    262: 
1.4       whiteley  263: <p>
                    264: It uses translated strings from <code>locale/xx-XX/help.dtd</code>.
                    265: </p>
                    266: 
                    267: 
                    268: 
                    269: 
1.1       whiteley  270: 
                    271: <h4>Run-time features</h4>
                    272: <p>
                    273: Calendar Help has some run-time features that you can use in your own help content pack.
                    274: These features provide support for:
                    275: <ul>
                    276: <li>Platform-specific content</li>
                    277: <li>Product-specific content</li>
                    278: <li>Standard HTML entities</li>
                    279: </ul>
                    280: </p>
                    281: 
                    282: <p>
                    283: You could implement some of these features by running separate builds and
                    284: providing separate installers.
                    285: By implementing them at run time, BuildHelp reduces the number of installers
                    286: that you have to build.
                    287: </p>
                    288: 
                    289: 
                    290: <h5>Platform-specific content</h5>
                    291: <p>
                    292: A CSS mechanism supports platform-specific content.
1.4       whiteley  293: It can hide or reveal sections of the text depending on the run-time platform,
                    294: and it can display platform-specific text defined as content for style classes.
1.1       whiteley  295: </p>
                    296: 
                    297: <p>
                    298: The file <code>helpContent.js</code> provides this mechanism by
                    299: determining the run-time platform and loading the appropriate
                    300: style sheet: <code>unix.css</code>, <code>mac.css</code> or <code>win.css</code>.
1.4       whiteley  301: These style sheets exist in each locale, because they may contain translatable strings.
1.1       whiteley  302: </p>
                    303: 
                    304: <p>
                    305: To make this work, load the code from every source file by including:
                    306: <blockquote><pre>
                    307: &lt;script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/&gt;
                    308: </pre></blockquote>
                    309: inside the <code>&lt;head&gt;</code> tag.
                    310: </p>
                    311: 
                    312: <p><strong>Note: </strong>
                    313: This feature does not work in the ToC, main index or gloassary index,
                    314: because it uses CSS.
                    315: A similar feature has been prototyped for the ToC, main index and gloassary index,
1.4       whiteley  316: but it requires a significant change to the help viewer so it has not been implemented in Calendar Help.
1.1       whiteley  317: </p>
                    318: 
                    319: 
                    320: 
                    321: <h5>Product-specific content</h5>
                    322: <p>
                    323: A DTD mechanism supports product-specific content for help content packs that are
                    324: written for extensions.
                    325: It can change certain words or phrases depending on the base product that the extenion is
                    326: installed into.
                    327: </p>
                    328: 
                    329: <p>
                    330: To make this work, there are four things to customize:
                    331: <ol>
                    332: <li>
                    333: The file <code>help.dtd</code> in each locale contains all the translated strings
                    334: for this mechanism.
                    335: </li>
                    336: <li>
                    337: The file <code>context.js</code> determines the base product and locale at run time.
1.2       whiteley  338: It writes <code>parent.dtd</code> if necessary.
1.1       whiteley  339: </li>
                    340: <li>
1.2       whiteley  341: Each source file loads <code>parent.dtd</code>.
1.1       whiteley  342: </li>
                    343: <li>
1.2       whiteley  344: Each index built by BuildHelp loads <code>parent.dtd</code>.
1.1       whiteley  345: See the section <a href="#options">Options</a> below for details.
                    346: </li>
                    347: </ol>
                    348: </p>
                    349: 
                    350: <p><strong>Notes: </strong><br>
                    351: (1) Part of this mechanism is specific to Calendar Help.
1.2       whiteley  352: Customizing it for other projects may require some difficult coding.
1.5     ! whiteley  353: <br>
1.2       whiteley  354: (2) An obsolete CSS mechanism for this has been removed.
1.1       whiteley  355: </p>
                    356: 
                    357: <h5>Standard HTML entities</h5>
                    358: <p>
                    359: BuildHelp supports HTML entities in entries in the glossary, index and ToC.
                    360: This allows writers to code, for example, e-acute (&eacute;) as <code>&amp;eacute;</code>
                    361: instead of <code>&amp;#233;</code> or the UTF-8 equivalent (<code>&Atilde;&copy;</code>).
                    362: </p>
                    363: 
                    364: <p>
                    365: If you do not need this, you can remove <code>xhtml11.dtd</code> from the
                    366: DTDs that BuildHelp includes.
                    367: See the section <a href="#options">Options</a> below for details.
                    368: </p>
                    369: 
                    370: 
                    371: 
                    372: <h4 id="options">Options</h4>
                    373: <p>
                    374: Some BuildHelp options can be set without modifying the program code.
                    375: To work with these options, open the URL <code>about:config</code> in
                    376: Firefox and filter on <code>buildhelp</code>.
                    377: Alternatively, close Firefox and edit the <code>prefs.js</code> file
                    378: in your profile directory.
                    379: </p>
                    380: 
                    381: 
                    382: <p>
                    383: To build jars and XPIs, BuildHelp uses a shell script.
                    384: By default the shell is <code>COMMAND.COM</code> and
                    385: the script is <code>ZIP.BAT</code>.
                    386: If your Windows system does not have <code>COMMAND.COM</code>,
                    387: you might be able to use <code>CMD.EXE</code>.
                    388: Or you might be able to use a different shell program and a
                    389: different script.
                    390: </p>

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