File:  [mozdev] / calendarhelp / www / buildguide.html
Revision 1.3: download - view: text, annotated - select for diffs - revision graph
Thu Apr 28 10:48:56 2005 UTC (14 years, 3 months ago) by whiteley
Branches: MAIN
CVS tags: HEAD
document changes to build (unfinished)

    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: <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: 
   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.
  265: It writes <code>parent.dtd</code> if necessary.
  266: </li>
  267: <li>
  268: Each source file loads <code>parent.dtd</code>.
  269: </li>
  270: <li>
  271: Each index built by BuildHelp loads <code>parent.dtd</code>.
  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.
  279: Customizing it for other projects may require some difficult coding.
  280: (2) An obsolete CSS mechanism for this has been removed.
  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>