File:  [mozdev] / calendarhelp / www / buildguide.html
Revision 1.2: download - view: text, annotated - select for diffs - revision graph
Fri Nov 12 17:20:51 2004 UTC (14 years, 9 months ago) by whiteley
Branches: MAIN
CVS tags: HEAD
build instructions for 0.0.2

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

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