Annotation of calendarhelp/www/build.html, revision 1.10

1.1       whiteley    1: <h5 class="page-header">Build</h5>
                      2: 
1.2       whiteley    3: 
1.1       whiteley    4: <p>
1.2       whiteley    5: This page describes how to build CalendarHelp from its source files.
                      6: </p>
                      7: 
1.8       whiteley    8: <h4>Viewing individual source files</h4>
1.2       whiteley    9: <p>
1.7       whiteley   10: If you are a writer or translator, you can test an individual source file
                     11: by viewing it in a Mozilla browser.
1.9       whiteley   12: Use the stylesheet <code>draft.css</code> and the bindings <code>draft.xbl</code>
                     13: supplied with the English source.
1.2       whiteley   14: </p>
                     15: 
                     16: <p>
1.7       whiteley   17: You can customize your view of the source files by modifying <code>draft.css</code>.
1.2       whiteley   18: </p>
                     19: 
                     20: 
                     21: <h4>Full build&mdash;overview</h4>
                     22: <p>
1.4       whiteley   23: The builder is a tool that runs in Firefox on Windows.
                     24: You might be able to make it run in a different browser or on a different platform,
                     25: but these variations are not supported.
1.2       whiteley   26: </p>
                     27: 
1.4       whiteley   28: <p>
                     29: The builder requires an external ZIP tool from
                     30: <a href="http://www.info-zip.org">Info-ZIP</a>.
                     31: </p>
                     32: 
                     33: <p>
                     34: The builder works on local copies of the source files on your computer.
                     35: Use a CVS client to get the source files.
                     36: The builder does not pull them.
                     37: </p>
                     38: 
                     39: <p>
                     40: For additional information about the builder, see
                     41: <a href="buildguide.html">Building help for other projects</a>.
                     42: </p>
                     43: 
                     44: 
1.2       whiteley   45: <h5>Source files</h5>
                     46: <p>
                     47: You must have copies of all the source files that the builder needs, in the
                     48: same directory structure that you find in CVS.
                     49: You do not need all the source files for the project&mdash;only the files
                     50: that are required for the parts that you want to build.
                     51: </p>
                     52: 
                     53: <p>
1.4       whiteley   54: Place the source files in any base directory on your computer.
1.2       whiteley   55: This base directory corresponds to the <code>src</code> directory in CVS.
                     56: You can use any name you like for the base directory&mdash;it does not have to be <code>src</code>.
                     57: </p>
                     58: 
                     59: <p>
                     60: Inside your base directory, keep the directory names and structure the same as in CVS.
1.4       whiteley   61: </p>
                     62: 
                     63: <p>
                     64: You can store additional files and directories in most places in the
                     65: directory structure without affecting the build,
                     66: but there are some exceptions:
                     67: <ul>
                     68: <li>Do not store extra <code>.xhtml</code> files in the same directory as the
                     69: source files for a locale, because the builder will try to index them.</li>
                     70: <li>Do not store extra files in the <code>install</code> directory,
1.7       whiteley   71: because the builder might try to include them in the XPIs.</li>
1.4       whiteley   72: </ul>
1.2       whiteley   73: </p>
                     74: 
                     75: 
                     76: <h5>What the builder does</h5>
                     77: <p>
                     78: The builder can build each of CalendarHelp's locales.
                     79: </p>
                     80: 
                     81: <p>
1.4       whiteley   82: For each locale, it can build:
1.2       whiteley   83: <ul>
1.4       whiteley   84: <li>The indexes</li>
                     85: <li>The jar file</li>
                     86: <li>The XPI installer</li>
1.2       whiteley   87: </ul>
                     88: </p>
                     89: 
                     90: <h5>Indexes</h5>
                     91: <p>
                     92: There are four indexes.
                     93: Three of the indexes are built in each locale.
                     94: They correspond to panels in the Help sidebar:
                     95: <ul>
                     96: <li>Glossary</li>
                     97: <li>Main index</li>
1.4       whiteley   98: <li>Table of contents (ToC)</li>
1.2       whiteley   99: </ul>
                    100: </p>
                    101: 
                    102: <p>
                    103: The fourth is only built in en-US, because it has no translatable content.
                    104: This index maps user-interface elements to help topics:
                    105: <ul>
                    106: <li>Context map</li>
                    107: </ul>
                    108: </p>
                    109: 
1.10    ! whiteley  110: <p><strong>Note: </strong>
        !           111: If you find copies of the indexes stored in CVS,
        !           112: this is by mistake because they are not source files.
        !           113: If you want to see the indexes, extract them from the jar.
1.4       whiteley  114: </p>
                    115: 
                    116: 
                    117: <h5>Jar file</h5>
                    118: <p>
                    119: There is one jar for each locale.
                    120: The builder stores it in the <code>install</code> directory
                    121: for the locale, in the <code>chrome</code> directory there.
                    122: For example, it stores the English jar as:
                    123: <blockquote>
1.8       whiteley  124: <code><i>base</i>/calendarhelp/install/en-US/chrome/calendarhelp-en-US.jar</code>
1.4       whiteley  125: </blockquote>
                    126: </p>
                    127: 
                    128: <p>
                    129: The jars are not stored in CVS.
1.10    ! whiteley  130: If you want to see a jar, either install Calendar Help or
        !           131: extract the jar from the XPI installer.
1.2       whiteley  132: </p>
                    133: 
1.4       whiteley  134: 
                    135: <h5>XPI installers</h5>
1.2       whiteley  136: <p>
1.4       whiteley  137: There is one XPI installer for each locale.
                    138: Each installer works in all the base products:
1.2       whiteley  139: <ul>
                    140: <li>Sunbird</li>
                    141: <li>Thunderbird</li>
                    142: <li>Firefox</li>
                    143: <li>Mozilla Application Suite</li>
1.7       whiteley  144: <li>Netscape</li>
1.2       whiteley  145: </ul>
1.6       whiteley  146: </p>
                    147: 
                    148: <p>
1.4       whiteley  149: The builder stores it in the <code>install</code> directory
                    150: for the locale, adding the version string and the locale name to the file name.
                    151: For example, it stores the English XPI for version 0.1 as:
                    152: <blockquote>
                    153: <code><i>base</i>/calendarhelp/install/en-US/calendarhelp-0.1-en-US.xpi</code>.
                    154: </blockquote>
                    155: </p>
                    156: 
                    157: <p>
                    158: The XPIs are stored in CVS, but not in this directory.
                    159: Instead, they are in the project's downloads directory.
1.7       whiteley  160: You cannot download them directly from this site.
1.10    ! whiteley  161: You can only download them from a mirror site.
1.2       whiteley  162: </p>
                    163: 
1.4       whiteley  164: 
1.2       whiteley  165: <h4>What you need to build</h4>
                    166: <p>
                    167: It is likely that you do not need to build everything.
                    168: You only need to build the parts that you are interested in, and that depend
                    169: on source that has changed.
                    170: </p>
                    171: 
                    172: <p>
                    173: For example, if you are a writer or translator, then it is likely that you
                    174: only need to test the changes that you have made.
                    175: </p>
                    176: 
                    177: <p>
                    178: If you build more parts than you really need, it does not do any harm.
                    179: It only forces you to download more source files,
                    180: and it makes the build process take longer.
                    181: </p>
                    182: 
                    183: <h5>What writers need to build</h5>
                    184: <p>
                    185: If you are a writer writing English help, then you can use the builder to test
                    186: the changes you have made.
                    187: </p>
                    188: 
                    189: <p>
                    190: You only need to build the en-US locale.
                    191: </p>
                    192: 
                    193: <p>
                    194: You only need to build three of the indexes:
                    195: <ul>
                    196: <li>Main index</li>
                    197: <li>Table of contents</li>
                    198: <li>Context map</li>
                    199: </ul>
                    200: </p>
                    201: 
                    202: <p><strong>Note:</strong>
                    203: If you are the writer assigned to the glossary, then of course you
                    204: only need to build the glossary index and the main index.
                    205: </p>
                    206: 
                    207: <p>
1.4       whiteley  208: You need to build the jar.
1.2       whiteley  209: </p>
                    210: 
                    211: <p>
                    212: You do not need to build any installer.
1.4       whiteley  213: You can manually copy the jar, replacing your old version.
1.2       whiteley  214: </p>
                    215: 
                    216: 
                    217: <h5>What translators need to build</h5>
                    218: <p>
                    219: If you are a translator, then you can use the builder to test
                    220: your translation.
                    221: </p>
                    222: 
                    223: <p>
                    224: You only need to build the locale that you are working on.
                    225: </p>
                    226: 
                    227: <p>
                    228: You only need to build three of the indexes:
                    229: <ul>
                    230: <li>Glossary</li>
                    231: <li>Main index</li>
                    232: <li>Table of contents</li>
                    233: </ul>
                    234: </p>
                    235: 
                    236: <p>
1.4       whiteley  237: You need to build the jar.
1.2       whiteley  238: </p>
                    239: 
                    240: <p>
                    241: You do not need to build any installer.
1.4       whiteley  242: You can manually copy the jar, replacing your old version.
1.2       whiteley  243: </p>
                    244: 
                    245: 
                    246: 
                    247: <h4>Installing the builder</h4>
                    248: <p>
                    249: To install the builder:
                    250: <ol>
1.5       whiteley  251: <li>Download
1.6       whiteley  252: <a href="http://downloads.mozdev.org/calendarhelp/buildhelp.jar"><code>buildhelp.jar</code></a>
1.5       whiteley  253: into Firefox's <code>chrome</code> directory.
                    254: </li>
                    255: 
                    256: <li>
                    257: Close Firefox.
                    258: </li>
                    259: 
                    260: <li>
                    261: In Firefox's <code>chrome</code> directory, delete the file
1.6       whiteley  262: <code>chrome.rdf</code>. (See step 5.)
1.5       whiteley  263: </li>
                    264: 
                    265: <li>
1.6       whiteley  266: Edit the file <code>installed-chrome.txt</code>, and at the end add this line
1.5       whiteley  267: (by copying and pasting from here):
                    268: <pre>
                    269: content,install,url,jar:resource:/chrome/buildhelp.jar!/content/buildhelp/
                    270: </pre>
                    271: </li>
                    272: 
                    273: <li>
                    274: Restart Firefox.
1.6       whiteley  275: It automatically rebuilds <code>chrome.rdf</code>.
1.5       whiteley  276: </li>
                    277: 
1.10    ! whiteley  278: <li>Open the following URL and bookmark it:
1.2       whiteley  279: <blockquote><pre>
1.4       whiteley  280: chrome://buildhelp/content
1.2       whiteley  281: </pre></blockquote>
                    282: </li>
1.5       whiteley  283: 
1.2       whiteley  284: </ol>
                    285: </p>
                    286: 
1.4       whiteley  287: 
1.2       whiteley  288: <h4>Running the builder</h4>
                    289: <p>
                    290: To run the builder, open its bookmarked URL.
                    291: Specify:
                    292: <ul>
1.4       whiteley  293: <li>The package name (<code>calendarhelp</code>)</li>
                    294: <li>A version string (optional)</li>
                    295: <li>The base directory where the source files are stored on your local machine</li>
                    296: <li>The locales that you want to build</li>
                    297: <li>The build steps that you want</li>
1.2       whiteley  298: </ul>
1.6       whiteley  299: </p>
                    300: 
                    301: <p>
1.2       whiteley  302: Press the Go button.
                    303: Look for error messages in the Status area.
                    304: </p>
                    305: 
1.6       whiteley  306: <p><strong>Note:</strong>
                    307: The builder is sensitive to tagging errors in source files,
                    308: but it simply fails to process the files without specifying what is wrong.
1.7       whiteley  309: If this happens, check each source file by viewing it in a Mozilla browser.
1.10    ! whiteley  310: The browser identifies the errors.
1.6       whiteley  311: </p>
                    312: 
1.4       whiteley  313: <h5 id="options">Defaults and options</h5>
1.2       whiteley  314: <p>
1.10    ! whiteley  315: You can store some builder defaults in <code>buildhelp.ini</code>
        !           316: in Firefox's <code>res</code> directory.
        !           317: For example, the file can contain settings like these,
        !           318: corresponding to fields in the user interface:
        !           319: <pre>
        !           320: proj.1=calendarhelp
        !           321: proj.1.version=0.1
        !           322: proj.1.base=F:\\Projects
        !           323: proj.1.subdir=false
        !           324: </pre>
        !           325: </p>
        !           326: 
        !           327: <p>
1.4       whiteley  328: Some builder defaults and options are stored as user preferences.
                    329: To change them, go to the URL <code>about:config</code>
                    330: and filter on <code>buildhelp</code>.
1.2       whiteley  331: </p>
                    332: 
                    333: 

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