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

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: <li>Product name entities</li>
        !           196: </ul>
        !           197: </p>
        !           198: 
        !           199: <p>
        !           200: You could implement some of these features by running separate builds and
        !           201: providing separate installers.
        !           202: By implementing them at run time, BuildHelp reduces the number of installers
        !           203: that you have to build.
        !           204: </p>
        !           205: 
        !           206: 
        !           207: <h5>Platform-specific content</h5>
        !           208: <p>
        !           209: A CSS mechanism supports platform-specific content.
        !           210: It can hide or reveal sections of the source text depending on the
        !           211: run-time platform,
        !           212: and it can display platform-specific text defined as content for
        !           213: style classes.
        !           214: </p>
        !           215: 
        !           216: <p>
        !           217: The file <code>helpContent.js</code> provides this mechanism by
        !           218: determining the run-time platform and loading the appropriate
        !           219: style sheet: <code>unix.css</code>, <code>mac.css</code> or <code>win.css</code>.
        !           220: These style sheets exist in each locale, because they may contain
        !           221: translatable strings.
        !           222: </p>
        !           223: 
        !           224: <p>
        !           225: To make this work, load the code from every source file by including:
        !           226: <blockquote><pre>
        !           227: &lt;script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/&gt;
        !           228: </pre></blockquote>
        !           229: inside the <code>&lt;head&gt;</code> tag.
        !           230: </p>
        !           231: 
        !           232: <p><strong>Note: </strong>
        !           233: This feature does not work in the ToC, main index or gloassary index,
        !           234: because it uses CSS.
        !           235: A similar feature has been prototyped for the ToC, main index and gloassary index,
        !           236: but it requires a significant change to the help viewer so it has not been implemented
        !           237: in Calendar Help.
        !           238: </p>
        !           239: 
        !           240: 
        !           241: 
        !           242: <h5>Product-specific content</h5>
        !           243: <p>
        !           244: A DTD mechanism supports product-specific content for help content packs that are
        !           245: written for extensions.
        !           246: It can change certain words or phrases depending on the base product that the extenion is
        !           247: installed into.
        !           248: </p>
        !           249: 
        !           250: <p>
        !           251: To make this work, there are four things to customize:
        !           252: <ol>
        !           253: <li>
        !           254: The file <code>help.dtd</code> in each locale contains all the translated strings
        !           255: for this mechanism.
        !           256: </li>
        !           257: <li>
        !           258: The file <code>context.js</code> determines the base product and locale at run time.
        !           259: It writes <code><i>projectname</i>.dtd</code> if necessary.
        !           260: </li>
        !           261: <li>
        !           262: Each source file loads <code><i>projectname</i>.dtd</code>.
        !           263: </li>
        !           264: <li>
        !           265: Each index built by BuildHelp loads <code><i>projectname</i>.dtd</code>.
        !           266: See the section <a href="#options">Options</a> below for details.
        !           267: </li>
        !           268: </ol>
        !           269: </p>
        !           270: 
        !           271: <p><strong>Notes: </strong><br>
        !           272: (1) Part of this mechanism is specific to Calendar Help.
        !           273: Customizing it for other projects may require some difficult coding
        !           274: (at step 2, above) to determine the base product exactly.<br>
        !           275: (2) A CSS mechanism for this still exists, but is deprecated.
        !           276: It does not work in the ToC or index.
        !           277: It will be removed.
        !           278: </p>
        !           279: 
        !           280: <h5>Standard HTML entities</h5>
        !           281: <p>
        !           282: BuildHelp supports HTML entities in entries in the glossary, index and ToC.
        !           283: This allows writers to code, for example, e-acute (&eacute;) as <code>&amp;eacute;</code>
        !           284: instead of <code>&amp;#233;</code> or the UTF-8 equivalent (<code>&Atilde;&copy;</code>).
        !           285: </p>
        !           286: 
        !           287: <p>
        !           288: If you do not need this, you can remove <code>xhtml11.dtd</code> from the
        !           289: DTDs that BuildHelp includes.
        !           290: See the section <a href="#options">Options</a> below for details.
        !           291: </p>
        !           292: 
        !           293: 
        !           294: <h5>Product name entities</h5>
        !           295: <p>
        !           296: BuildHelp supports Mozilla product name entities in entries in the glossary, index and ToC.
        !           297: This allows writers to code, for example, <code>&amp;brandShortName;</code>
        !           298: instead of hard-coding the name of the product.
        !           299: </p>
        !           300: 
        !           301: <p>
        !           302: If you do not need this, you can remove <code>brand.dtd</code> from the
        !           303: DTDs that BuildHelp includes.
        !           304: See the section <a href="#options">Options</a> below for details.
        !           305: </p>
        !           306: 
        !           307: 
        !           308: 
        !           309: <h4 id="options">Options</h4>
        !           310: <p>
        !           311: Some BuildHelp options can be set without modifying the program code.
        !           312: To work with these options, open the URL <code>about:config</code> in
        !           313: Firefox and filter on <code>buildhelp</code>.
        !           314: Alternatively, close Firefox and edit the <code>prefs.js</code> file
        !           315: in your profile directory.
        !           316: </p>
        !           317: 
        !           318: <p>
        !           319: In the list of DTDs, BuildHelp ignores any empty string.
        !           320: The special DTD file name <code>[projectname]</code> resolves to the actual
        !           321: project name that you specify in BuildHelp's UI.
        !           322: </p>
        !           323: 
        !           324: <p>
        !           325: To build jars and XPIs, BuildHelp uses a shell script.
        !           326: By default the shell is <code>COMMAND.COM</code> and
        !           327: the script is <code>ZIP.BAT</code>.
        !           328: If your Windows system does not have <code>COMMAND.COM</code>,
        !           329: you might be able to use <code>CMD.EXE</code>.
        !           330: Or you might be able to use a different shell program and a
        !           331: different script.
        !           332: </p>

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