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

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>
                     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>.
1.4     ! whiteley   92: By default the base locale is <code>en-US</code>,
        !            93: and that is the base locale shown on this page.
1.1       whiteley   94: For information on how to change it, see the section
                     95: <a href="#options">Options</a> below.
                     96: </p>
                     97: 
                     98: <p>
                     99: Your content pack has a master file in each locale that defines the names
                    100: of certain parts of the content.
                    101: But BuildHelp ignores your master file and uses names that are hard coded.
                    102: So, to use BuildHelp you must make the names in your master file match
                    103: the names that BuildHelp uses.
                    104: </p>
                    105: 
                    106: <p>
                    107: One way to do this is to use Calendar Help's <code>help.rdf</code>
                    108: as the basis for your project's master file, changing only those
                    109: things that you really need to change.
                    110: </p>
                    111: 
1.4     ! whiteley  112: <p>
        !           113: The source files for each locale are in the <code>text</code> directory,
        !           114: in a subdirectory for the locale.
        !           115: Other translatable files are in the <code>locale</code> directory,
        !           116: in a subdirectory for the locale.
        !           117: </p>
        !           118: 
1.1       whiteley  119: 
                    120: 
                    121: <h5>The glossary</h5>
                    122: <p>
1.4     ! whiteley  123: The source file for the glossary is <code>text/xx-XX/glossary.xhtml</code>.
1.1       whiteley  124: </p>
                    125: 
                    126: <p>
1.4     ! whiteley  127: BuildHelp builds <code>locale/xx-XX/glosary.rdf</code>,
        !           128: using <code>build/build.properties</code> to supply the DTDs.
1.1       whiteley  129: </p>
                    130: 
                    131: 
                    132: <h5>The main index</h5>
                    133: <p>
1.4     ! whiteley  134: The source files for the main index are all the <code>text/xx-XX/*.xhtml</code> files.
1.1       whiteley  135: </p>
                    136: 
                    137: <p>
1.4     ! whiteley  138: BuildHelp builds <code>locale/xx-XX/index.rdf</code>,
        !           139: using <code>build/build.properties</code> to supply the DTDs.
1.1       whiteley  140: </p>
                    141: 
                    142: <p>
                    143: BuildHelp does not include a complete alphabet in the index&mdash;only
                    144: the letters that are actually used.
                    145: </p>
                    146: 
                    147: 
                    148: 
                    149: <h5>The table of contents (ToC)</h5>
                    150: <p>
1.4     ! whiteley  151: A special file, <code>locale/en-US/files.rdf</code>, lists the source files for the ToC.
1.1       whiteley  152: It exists only in the base locale, because it has no translatable content.
                    153: </p>
                    154: 
                    155: <p>
1.4     ! whiteley  156: Create <code>locale/en-US/files.rdf</code> manually, listing all the <code>.xhtml</code> files
1.1       whiteley  157: that you want to include in the ToC, in the sequence that you require.
                    158: Normally, you include all the source files except the glossary.
                    159: Copy the format of Calendar Help's <code>files.rdf</code>.
                    160: </p>
                    161: 
                    162: <p>
1.4     ! whiteley  163: BuildHelp builds <code>locale/xx-XX/toc.rdf</code>,
        !           164: using <code>build/build.properties</code> to supply the DTDs.
        !           165: It builds entries only from <code>h1</code>, <code>h2</code>,
        !           166: <code>h3</code> and <code>h4</code> tags.
1.1       whiteley  167: </p>
                    168: 
                    169: <p>
                    170: There is no need to package <code>files.rdf</code> for installation.
                    171: It is not used at run time.
                    172: </p>
                    173: 
                    174: 
1.4     ! whiteley  175: 
1.1       whiteley  176: <h5>The context map</h5>
                    177: <p>
1.4     ! whiteley  178: The source files for the context map are all the <code>text/en-US/*.xhtml</code>
        !           179: files for the base locale.
1.1       whiteley  180: The context map has no translatable content.
                    181: </p>
                    182: 
                    183: <p>
                    184: BuildHelp builds <code>context.rdf</code> in the
                    185: <code><i>projectname</i>/content/<i>projectname</i></code> directory.
                    186: </p>
                    187: 
                    188: <p>
                    189: To make the context map work, you must activate the F1 or Help key in every window
                    190: of the product that you are writing help for.
                    191: If you own the product, then you can do this directly.
                    192: Otherwise you must do it using overlays.
                    193: For example, see Calendar Help's <code>dialogOverlay.xul</code> file.
                    194: </p>
                    195: 
                    196: <p>
1.4     ! whiteley  197: The JavaScript code that reads the map is in Calendar Help's <code>context.js</code>.
        !           198: To adapt this file for your own project, you must change the project name throughout
        !           199: and remove or rewrite some code that is specific to Calendar.
        !           200: </p>
        !           201: 
        !           202: 
        !           203: 
        !           204: 
        !           205: <h5>The jar file</h5>
        !           206: <p>
        !           207: To create a jar file for the content pack, BuildHelp first converts the source files
        !           208: <code>text/xx-XX/*.xhtml</code> to a form that the help viewer can use, writing the
        !           209: converted files to <code>locale/xx-XX/*.xhtml</code>.
        !           210: It uses <code>build/build.properties</code> to supply the DTDs and the tags in the head.
        !           211: It removes <context> and <index> tags, which are not needed at run time.
        !           212: This conversion only runs on source files that have changed.
        !           213: </p>
        !           214: 
        !           215: <p>
        !           216: Then BuildHelp runs an external script to create the jar file.
        !           217: The default script is <code>build/ZIP.BAT</code>.
        !           218: </p>
        !           219: 
        !           220: <p>
        !           221: The resulting jar file is <code>install/xx-XX/chrome/projectname-xx_XX.jar</code>
        !           222: </p>
        !           223: 
        !           224: 
        !           225: 
        !           226: <h5>The XPI</h5>
        !           227: <p>
        !           228: To create an installable XPI for the content pack, BuildHelp first converts the
        !           229: installation files <code>install/install.js</code> and <code>install/install.rdf</code>
        !           230: for the locale by adding translated strings from <code>locale/xx-XX/install.properties</code>.
        !           231: It writes the converted files to <code>install/xx-XX/install.*</code>.
        !           232: </p>
        !           233: 
        !           234: <p>
        !           235: Then BuildHelp runs an external script to create the xpi file.
        !           236: The default script is <code>build/ZIP.BAT</code>.
        !           237: </p>
        !           238: 
        !           239: <p>
        !           240: The resulting XPI is <code>install/xx-XX/projectname-v.v-xx_XX.xpi</code>
        !           241: where <code>v.v</code> is the version number.
        !           242: </p>
        !           243: 
        !           244: 
        !           245: <h5>Online content (experimental)</h5>
        !           246: <p><strong>Note: </strong>
        !           247: This is work in progress.
        !           248: Currently, some features of the online content only work in English.
        !           249: </p>
        !           250: 
        !           251: <p>
        !           252: To create online content, BuildHelp first converts the source files
        !           253: <code>text/xx-XX/*.xhtml</code> to a form that the online viewer can use, writing the
        !           254: converted files to <code>www/xx-XX/*.xhtml</code>.
        !           255: It removes <context> and <index> tags, which are not needed at run time.
        !           256: This conversion only runs on source files that have changed.
        !           257: </p>
        !           258: 
        !           259: <p>
        !           260: It also converts the indexes <code>locale/xx-XX/*.rdf</code>, writing the
        !           261: converted files to <code>www/xx-XX/*.rdf</code>.
1.1       whiteley  262: </p>
                    263: 
1.4     ! whiteley  264: <p>
        !           265: It uses translated strings from <code>locale/xx-XX/help.dtd</code>.
        !           266: </p>
        !           267: 
        !           268: 
        !           269: 
        !           270: 
1.1       whiteley  271: 
                    272: <h4>Run-time features</h4>
                    273: <p>
                    274: Calendar Help has some run-time features that you can use in your own help content pack.
                    275: These features provide support for:
                    276: <ul>
                    277: <li>Platform-specific content</li>
                    278: <li>Product-specific content</li>
                    279: <li>Standard HTML entities</li>
                    280: </ul>
                    281: </p>
                    282: 
                    283: <p>
                    284: You could implement some of these features by running separate builds and
                    285: providing separate installers.
                    286: By implementing them at run time, BuildHelp reduces the number of installers
                    287: that you have to build.
                    288: </p>
                    289: 
                    290: 
                    291: <h5>Platform-specific content</h5>
                    292: <p>
                    293: A CSS mechanism supports platform-specific content.
1.4     ! whiteley  294: It can hide or reveal sections of the text depending on the run-time platform,
        !           295: and it can display platform-specific text defined as content for style classes.
1.1       whiteley  296: </p>
                    297: 
                    298: <p>
                    299: The file <code>helpContent.js</code> provides this mechanism by
                    300: determining the run-time platform and loading the appropriate
                    301: style sheet: <code>unix.css</code>, <code>mac.css</code> or <code>win.css</code>.
1.4     ! whiteley  302: These style sheets exist in each locale, because they may contain translatable strings.
1.1       whiteley  303: </p>
                    304: 
                    305: <p>
                    306: To make this work, load the code from every source file by including:
                    307: <blockquote><pre>
                    308: &lt;script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/&gt;
                    309: </pre></blockquote>
                    310: inside the <code>&lt;head&gt;</code> tag.
                    311: </p>
                    312: 
                    313: <p><strong>Note: </strong>
                    314: This feature does not work in the ToC, main index or gloassary index,
                    315: because it uses CSS.
                    316: A similar feature has been prototyped for the ToC, main index and gloassary index,
1.4     ! whiteley  317: but it requires a significant change to the help viewer so it has not been implemented in Calendar Help.
1.1       whiteley  318: </p>
                    319: 
                    320: 
                    321: 
                    322: <h5>Product-specific content</h5>
                    323: <p>
                    324: A DTD mechanism supports product-specific content for help content packs that are
                    325: written for extensions.
                    326: It can change certain words or phrases depending on the base product that the extenion is
                    327: installed into.
                    328: </p>
                    329: 
                    330: <p>
                    331: To make this work, there are four things to customize:
                    332: <ol>
                    333: <li>
                    334: The file <code>help.dtd</code> in each locale contains all the translated strings
                    335: for this mechanism.
                    336: </li>
                    337: <li>
                    338: The file <code>context.js</code> determines the base product and locale at run time.
1.2       whiteley  339: It writes <code>parent.dtd</code> if necessary.
1.1       whiteley  340: </li>
                    341: <li>
1.2       whiteley  342: Each source file loads <code>parent.dtd</code>.
1.1       whiteley  343: </li>
                    344: <li>
1.2       whiteley  345: Each index built by BuildHelp loads <code>parent.dtd</code>.
1.1       whiteley  346: See the section <a href="#options">Options</a> below for details.
                    347: </li>
                    348: </ol>
                    349: </p>
                    350: 
                    351: <p><strong>Notes: </strong><br>
                    352: (1) Part of this mechanism is specific to Calendar Help.
1.2       whiteley  353: Customizing it for other projects may require some difficult coding.
                    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>