File:  [mozdev] / calendarhelp / www / buildguide.html
Revision 1.4: download - view: text, annotated - select for diffs - revision graph
Fri Apr 29 08:41:05 2005 UTC (14 years, 3 months ago) by whiteley
Branches: MAIN
CVS tags: HEAD
document some builder changes

    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: 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.
   50: </p>
   51: 
   52: <p>
   53: For each locale, BuildHelp creates:
   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>
   60: <li>online content (experimental)</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 <code>en-US</code>,
   93: and that is the base locale shown on this page.
   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: 
  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: 
  119: 
  120: 
  121: <h5>The glossary</h5>
  122: <p>
  123: The source file for the glossary is <code>text/xx-XX/glossary.xhtml</code>.
  124: </p>
  125: 
  126: <p>
  127: BuildHelp builds <code>locale/xx-XX/glosary.rdf</code>,
  128: using <code>build/build.properties</code> to supply the DTDs.
  129: </p>
  130: 
  131: 
  132: <h5>The main index</h5>
  133: <p>
  134: The source files for the main index are all the <code>text/xx-XX/*.xhtml</code> files.
  135: </p>
  136: 
  137: <p>
  138: BuildHelp builds <code>locale/xx-XX/index.rdf</code>,
  139: using <code>build/build.properties</code> to supply the DTDs.
  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>
  151: A special file, <code>locale/en-US/files.rdf</code>, lists the source files for the ToC.
  152: It exists only in the base locale, because it has no translatable content.
  153: </p>
  154: 
  155: <p>
  156: Create <code>locale/en-US/files.rdf</code> manually, listing all the <code>.xhtml</code> files
  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>
  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.
  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: 
  175: 
  176: <h5>The context map</h5>
  177: <p>
  178: The source files for the context map are all the <code>text/en-US/*.xhtml</code>
  179: files for the base locale.
  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>
  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>.
  262: </p>
  263: 
  264: <p>
  265: It uses translated strings from <code>locale/xx-XX/help.dtd</code>.
  266: </p>
  267: 
  268: 
  269: 
  270: 
  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.
  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.
  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>.
  302: These style sheets exist in each locale, because they may contain translatable strings.
  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,
  317: but it requires a significant change to the help viewer so it has not been implemented in Calendar Help.
  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.
  339: It writes <code>parent.dtd</code> if necessary.
  340: </li>
  341: <li>
  342: Each source file loads <code>parent.dtd</code>.
  343: </li>
  344: <li>
  345: Each index built by BuildHelp loads <code>parent.dtd</code>.
  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.
  353: Customizing it for other projects may require some difficult coding.
  354: (2) An obsolete CSS mechanism for this has been removed.
  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>