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

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.6     ! whiteley    8: <p><strong>Note: </strong>
        !             9: Parts of BuildHelp might be specially coded in a way that only works in Calendar Help.
        !            10: The general intention is to allow BuildHelp to be used with other projects,
        !            11: but if your project's requirements differ from Calendar Help's requirements,
        !            12: then you might have to modify BuildHelp's code.
        !            13: </p>
        !            14: 
        !            15: 
1.1       whiteley   16: <h4>Overview</h4>
                     17: <p>
                     18: The BuildHelp tool is part of the Calendar Help project.
                     19: It is designed to build the help for Calendar and Sunbird.
1.6     ! whiteley   20: But you can use BuildHelp to build other projects,
        !            21: especially if they contain help content packs.
1.1       whiteley   22: </p>
                     23: 
                     24: <p>
                     25: This page contains information about how to set up the source files
1.6     ! whiteley   26: for your project and help content pack so that you can use it with BuildHelp.
1.1       whiteley   27: </p>
                     28: 
                     29: <p>
                     30: For basic information about help content packs, see:
                     31: <a href="">Content Packs</a>.
                     32: Pay no attention to the details of the RDF files described there,
                     33: because BuildHelp builds these RDF files for you automatically.
                     34: </p>
                     35: 
                     36: <p>
                     37: For information about how to write help source files suitable for
                     38: BuildHelp, see the
                     39: <a href="write.html">Guidelines for writers</a> and
                     40: <a href="translate.html">Guidelines for translators</a> on this site.
                     41: </p>
                     42: 
                     43: <p>
                     44: For information about how to install and use BuildHelp, see
                     45: <a href="build.html">Build</a> on this site.
                     46: </p>
                     47: 
                     48: 
                     49: <h5>What BuildHelp does</h5>
                     50: <p>
                     51: BuildHelp automates the building of indexes, jars and XPI installers for
                     52: help content packs.
1.4       whiteley   53: It can also build content for an experimental online viewer.
                     54: </p>
                     55: 
                     56: <p>
                     57: BuildHelp supports translated content in more than one locale.
                     58: On this page, the locale <code>xx-XX</code> means the locale that you are currently building.
1.1       whiteley   59: </p>
                     60: 
                     61: <p>
1.4       whiteley   62: For each locale, BuildHelp creates:
1.1       whiteley   63: <ul>
                     64: <li><code>glossary.rdf</code>, the glossary index</li>
                     65: <li><code>index.rdf</code>, the main index</li>
                     66: <li><code>toc.rdf</code>, the table of contents</li>
                     67: <li>a <code>.jar</code> file containing the content pack</li>
                     68: <li>a XPI installer</li>
1.4       whiteley   69: <li>online content (experimental)</li>
1.1       whiteley   70: </ul>
                     71: </p>
                     72: 
                     73: <p>
1.5       whiteley   74: It also creates one file that applies to all locales:
1.1       whiteley   75: <ul>
                     76: <li><code>context.rdf</code>, the context map</li>
                     77: </ul>
                     78: </p>
                     79: 
                     80: <p>
1.6     ! whiteley   81: In addition, BuildHelp can copy project source files from a sandbox (or developement directory)
        !            82: to a CVS directory, adding license information to the files.
        !            83: </p>
        !            84: 
        !            85: <p>
1.1       whiteley   86: You can choose which parts of BuildHelp are appropriate for your project.
                     87: For example, if you do not want a context map, you do not have to build it.
                     88: </p>
                     89: 
                     90: 
                     91: <h4>Source files for your content pack</h4>
                     92: <p>
                     93: Create a local directory structure for your project similar to
                     94: Calendar Help's directory structure on CVS.
1.6     ! whiteley   95: This local directory structure is your CVS area.
1.1       whiteley   96: </p>
                     97: 
                     98: <p>
1.6     ! whiteley   99: If you wish to develop your project in a sandbox area,
        !           100: create a second similar local directory structure.
        !           101: A sandbox area allows you to make experimental changes to source files
        !           102: without affectng files that are under CVS control.
        !           103: The files in a sandbox area are private to you,
        !           104: so they do not contain license information.
        !           105: </p>
        !           106: 
        !           107: <p>
        !           108: One way to create a local directory structure is to check out Calendar Help's source files
1.1       whiteley  109: from CVS, then rename the directories and change the files as required
                    110: for your project.
                    111: </p>
                    112: 
                    113: <p>
                    114: BuildHelp treats one locale as the <i>base locale</i>.
1.4       whiteley  115: By default the base locale is <code>en-US</code>,
                    116: and that is the base locale shown on this page.
1.1       whiteley  117: For information on how to change it, see the section
                    118: <a href="#options">Options</a> below.
                    119: </p>
                    120: 
                    121: <p>
                    122: Your content pack has a master file in each locale that defines the names
                    123: of certain parts of the content.
                    124: But BuildHelp ignores your master file and uses names that are hard coded.
                    125: So, to use BuildHelp you must make the names in your master file match
                    126: the names that BuildHelp uses.
                    127: </p>
                    128: 
                    129: <p>
                    130: One way to do this is to use Calendar Help's <code>help.rdf</code>
                    131: as the basis for your project's master file, changing only those
                    132: things that you really need to change.
                    133: </p>
                    134: 
1.4       whiteley  135: <p>
                    136: The source files for each locale are in the <code>text</code> directory,
                    137: in a subdirectory for the locale.
                    138: Other translatable files are in the <code>locale</code> directory,
                    139: in a subdirectory for the locale.
                    140: </p>
                    141: 
1.1       whiteley  142: 
                    143: 
                    144: <h5>The glossary</h5>
                    145: <p>
1.4       whiteley  146: The source file for the glossary is <code>text/xx-XX/glossary.xhtml</code>.
1.1       whiteley  147: </p>
                    148: 
                    149: <p>
1.4       whiteley  150: BuildHelp builds <code>locale/xx-XX/glosary.rdf</code>,
                    151: using <code>build/build.properties</code> to supply the DTDs.
1.1       whiteley  152: </p>
                    153: 
                    154: 
                    155: <h5>The main index</h5>
                    156: <p>
1.4       whiteley  157: The source files for the main index are all the <code>text/xx-XX/*.xhtml</code> files.
1.1       whiteley  158: </p>
                    159: 
                    160: <p>
1.4       whiteley  161: BuildHelp builds <code>locale/xx-XX/index.rdf</code>,
                    162: using <code>build/build.properties</code> to supply the DTDs.
1.1       whiteley  163: </p>
                    164: 
                    165: <p>
                    166: BuildHelp does not include a complete alphabet in the index&mdash;only
                    167: the letters that are actually used.
                    168: </p>
                    169: 
                    170: 
                    171: 
                    172: <h5>The table of contents (ToC)</h5>
                    173: <p>
1.4       whiteley  174: A special file, <code>locale/en-US/files.rdf</code>, lists the source files for the ToC.
1.1       whiteley  175: It exists only in the base locale, because it has no translatable content.
                    176: </p>
                    177: 
                    178: <p>
1.4       whiteley  179: Create <code>locale/en-US/files.rdf</code> manually, listing all the <code>.xhtml</code> files
1.1       whiteley  180: that you want to include in the ToC, in the sequence that you require.
                    181: Normally, you include all the source files except the glossary.
                    182: Copy the format of Calendar Help's <code>files.rdf</code>.
                    183: </p>
                    184: 
                    185: <p>
1.4       whiteley  186: BuildHelp builds <code>locale/xx-XX/toc.rdf</code>,
                    187: using <code>build/build.properties</code> to supply the DTDs.
                    188: It builds entries only from <code>h1</code>, <code>h2</code>,
                    189: <code>h3</code> and <code>h4</code> tags.
1.1       whiteley  190: </p>
                    191: 
                    192: <p>
                    193: There is no need to package <code>files.rdf</code> for installation.
                    194: It is not used at run time.
                    195: </p>
                    196: 
                    197: 
1.4       whiteley  198: 
1.1       whiteley  199: <h5>The context map</h5>
                    200: <p>
1.4       whiteley  201: The source files for the context map are all the <code>text/en-US/*.xhtml</code>
                    202: files for the base locale.
1.1       whiteley  203: The context map has no translatable content.
                    204: </p>
                    205: 
                    206: <p>
                    207: BuildHelp builds <code>context.rdf</code> in the
                    208: <code><i>projectname</i>/content/<i>projectname</i></code> directory.
                    209: </p>
                    210: 
                    211: <p>
                    212: To make the context map work, you must activate the F1 or Help key in every window
                    213: of the product that you are writing help for.
                    214: If you own the product, then you can do this directly.
                    215: Otherwise you must do it using overlays.
                    216: For example, see Calendar Help's <code>dialogOverlay.xul</code> file.
                    217: </p>
                    218: 
                    219: <p>
1.4       whiteley  220: The JavaScript code that reads the map is in Calendar Help's <code>context.js</code>.
                    221: To adapt this file for your own project, you must change the project name throughout
                    222: and remove or rewrite some code that is specific to Calendar.
                    223: </p>
                    224: 
                    225: 
                    226: 
                    227: 
                    228: <h5>The jar file</h5>
                    229: <p>
                    230: To create a jar file for the content pack, BuildHelp first converts the source files
                    231: <code>text/xx-XX/*.xhtml</code> to a form that the help viewer can use, writing the
                    232: converted files to <code>locale/xx-XX/*.xhtml</code>.
                    233: It uses <code>build/build.properties</code> to supply the DTDs and the tags in the head.
1.6     ! whiteley  234: It removes <code>&lt;context&gt;</code> and <code>&lt;index&gt;</code> tags, which are not needed at run time,
        !           235: and applies some additional filters.
        !           236: It adds the tiny license specified in <code>build/build.properties</code>.
        !           237: </p>
        !           238: 
1.4       whiteley  239: This conversion only runs on source files that have changed.
                    240: </p>
                    241: 
                    242: <p>
                    243: Then BuildHelp runs an external script to create the jar file.
                    244: The default script is <code>build/ZIP.BAT</code>.
                    245: </p>
                    246: 
                    247: <p>
                    248: The resulting jar file is <code>install/xx-XX/chrome/projectname-xx_XX.jar</code>
                    249: </p>
                    250: 
                    251: 
                    252: 
                    253: <h5>The XPI</h5>
                    254: <p>
                    255: To create an installable XPI for the content pack, BuildHelp first converts the
                    256: installation files <code>install/install.js</code> and <code>install/install.rdf</code>
                    257: for the locale by adding translated strings from <code>locale/xx-XX/install.properties</code>.
                    258: It writes the converted files to <code>install/xx-XX/install.*</code>.
                    259: </p>
                    260: 
                    261: <p>
                    262: Then BuildHelp runs an external script to create the xpi file.
                    263: The default script is <code>build/ZIP.BAT</code>.
                    264: </p>
                    265: 
                    266: <p>
                    267: The resulting XPI is <code>install/xx-XX/projectname-v.v-xx_XX.xpi</code>
                    268: where <code>v.v</code> is the version number.
                    269: </p>
                    270: 
                    271: 
                    272: <h5>Online content (experimental)</h5>
                    273: <p><strong>Note: </strong>
                    274: This is work in progress.
                    275: Currently, some features of the online content only work in English.
                    276: </p>
                    277: 
                    278: <p>
                    279: To create online content, BuildHelp first converts the source files
                    280: <code>text/xx-XX/*.xhtml</code> to a form that the online viewer can use, writing the
                    281: converted files to <code>www/xx-XX/*.xhtml</code>.
1.6     ! whiteley  282: It removes <code>&lt;context&gt;</code> and <code>&lt;index&gt;</code> tags, which are not needed at run time,
        !           283: and applies some additional filters.
1.4       whiteley  284: This conversion only runs on source files that have changed.
                    285: </p>
                    286: 
                    287: <p>
                    288: It also converts the indexes <code>locale/xx-XX/*.rdf</code>, writing the
                    289: converted files to <code>www/xx-XX/*.rdf</code>.
1.1       whiteley  290: </p>
                    291: 
1.4       whiteley  292: <p>
                    293: It uses translated strings from <code>locale/xx-XX/help.dtd</code>.
                    294: </p>
                    295: 
                    296: 
                    297: 
1.6     ! whiteley  298: <h5>Update CVS from sandbox</h5>
        !           299: <p>
        !           300: If you develop your project in a sandbox area, BuildHelp can copy source files from
        !           301: there to your CVS area, adding license information to the files.
        !           302: BuildHelp only copies files that have changed.
        !           303: </p>
        !           304: 
        !           305: <p>
        !           306: <code>build/build.properties</code> supplies data for the update,
        !           307: specifying a list of source and target directories,
        !           308: a list of file names to hold back,
        !           309: and the text of the full license added.
        !           310: For an example of the format, see Calendar Help's <code>build/build.properties</code> file.
        !           311: </p>
        !           312: 
        !           313: <p>
        !           314: BuildHelp does not commit changes to CVS.
        !           315: Use a CVS client for this step.
        !           316: </p>
        !           317: 
        !           318: 
1.4       whiteley  319: 
1.1       whiteley  320: 
                    321: <h4>Run-time features</h4>
                    322: <p>
                    323: Calendar Help has some run-time features that you can use in your own help content pack.
                    324: These features provide support for:
                    325: <ul>
                    326: <li>Platform-specific content</li>
                    327: <li>Product-specific content</li>
                    328: <li>Standard HTML entities</li>
                    329: </ul>
                    330: </p>
                    331: 
                    332: <p>
                    333: You could implement some of these features by running separate builds and
                    334: providing separate installers.
                    335: By implementing them at run time, BuildHelp reduces the number of installers
                    336: that you have to build.
                    337: </p>
                    338: 
                    339: 
                    340: <h5>Platform-specific content</h5>
                    341: <p>
                    342: A CSS mechanism supports platform-specific content.
1.4       whiteley  343: It can hide or reveal sections of the text depending on the run-time platform,
                    344: and it can display platform-specific text defined as content for style classes.
1.1       whiteley  345: </p>
                    346: 
                    347: <p>
                    348: The file <code>helpContent.js</code> provides this mechanism by
                    349: determining the run-time platform and loading the appropriate
                    350: style sheet: <code>unix.css</code>, <code>mac.css</code> or <code>win.css</code>.
1.4       whiteley  351: These style sheets exist in each locale, because they may contain translatable strings.
1.1       whiteley  352: </p>
                    353: 
                    354: <p>
                    355: To make this work, load the code from every source file by including:
                    356: <blockquote><pre>
                    357: &lt;script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/&gt;
                    358: </pre></blockquote>
                    359: inside the <code>&lt;head&gt;</code> tag.
                    360: </p>
                    361: 
                    362: <p><strong>Note: </strong>
                    363: This feature does not work in the ToC, main index or gloassary index,
                    364: because it uses CSS.
                    365: A similar feature has been prototyped for the ToC, main index and gloassary index,
1.4       whiteley  366: but it requires a significant change to the help viewer so it has not been implemented in Calendar Help.
1.1       whiteley  367: </p>
                    368: 
                    369: 
                    370: 
                    371: <h5>Product-specific content</h5>
                    372: <p>
                    373: A DTD mechanism supports product-specific content for help content packs that are
                    374: written for extensions.
                    375: It can change certain words or phrases depending on the base product that the extenion is
                    376: installed into.
                    377: </p>
                    378: 
                    379: <p>
                    380: To make this work, there are four things to customize:
                    381: <ol>
                    382: <li>
                    383: The file <code>help.dtd</code> in each locale contains all the translated strings
                    384: for this mechanism.
                    385: </li>
                    386: <li>
                    387: The file <code>context.js</code> determines the base product and locale at run time.
1.2       whiteley  388: It writes <code>parent.dtd</code> if necessary.
1.1       whiteley  389: </li>
                    390: <li>
1.2       whiteley  391: Each source file loads <code>parent.dtd</code>.
1.1       whiteley  392: </li>
                    393: <li>
1.2       whiteley  394: Each index built by BuildHelp loads <code>parent.dtd</code>.
1.1       whiteley  395: See the section <a href="#options">Options</a> below for details.
                    396: </li>
                    397: </ol>
                    398: </p>
                    399: 
                    400: <p><strong>Notes: </strong><br>
                    401: (1) Part of this mechanism is specific to Calendar Help.
1.2       whiteley  402: Customizing it for other projects may require some difficult coding.
1.5       whiteley  403: <br>
1.2       whiteley  404: (2) An obsolete CSS mechanism for this has been removed.
1.1       whiteley  405: </p>
                    406: 
                    407: <h5>Standard HTML entities</h5>
                    408: <p>
                    409: BuildHelp supports HTML entities in entries in the glossary, index and ToC.
                    410: This allows writers to code, for example, e-acute (&eacute;) as <code>&amp;eacute;</code>
                    411: instead of <code>&amp;#233;</code> or the UTF-8 equivalent (<code>&Atilde;&copy;</code>).
                    412: </p>
                    413: 
                    414: <p>
1.6     ! whiteley  415: If you do not need this, you can remove <code>html.dtd</code> from the
1.1       whiteley  416: DTDs that BuildHelp includes.
                    417: See the section <a href="#options">Options</a> below for details.
                    418: </p>
                    419: 
                    420: 
                    421: 
1.6     ! whiteley  422: <h4 id="options">Project information and options</h4>
        !           423: <p>
        !           424: BuildHelp reads project information from a file <code>buildhelp.ini</code>
        !           425: in Firefox's <code>res</code> directory.
        !           426: For example, the file can contain settings like these,
        !           427: corresponding to fields in the user interface:
        !           428: <pre>
        !           429: proj.1=calendarhelp
        !           430: proj.1.version=0.1
        !           431: proj.1.base=F:\\Projects
        !           432: proj.1.subdir=false
        !           433: </pre>
        !           434: </p>
        !           435: 
        !           436: <p>
        !           437: To specify second and subsequent projects, add setings for <code>proj.2</code>, <i>etc</i>.
        !           438: </p>
        !           439: 
1.1       whiteley  440: <p>
1.6     ! whiteley  441: Some other BuildHelp options can be set.
1.1       whiteley  442: To work with these options, open the URL <code>about:config</code> in
                    443: Firefox and filter on <code>buildhelp</code>.
                    444: Alternatively, close Firefox and edit the <code>prefs.js</code> file
                    445: in your profile directory.
                    446: </p>
                    447: 
                    448: 
                    449: <p>
                    450: To build jars and XPIs, BuildHelp uses a shell script.
                    451: By default the shell is <code>COMMAND.COM</code> and
                    452: the script is <code>ZIP.BAT</code>.
                    453: If your Windows system does not have <code>COMMAND.COM</code>,
                    454: you might be able to use <code>CMD.EXE</code>.
                    455: Or you might be able to use a different shell program and a
                    456: different script.
                    457: </p>

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