source: documentation/trunk/manuals/README.html@ 17494

Last change on this file since 17494 was 17494, checked in by anna, 16 years ago

Updated tutorials and associated files.

  • Property svn:keywords set to Author Date Id Revision
File size: 13.0 KB
3<title>Greenstone Manuals README</title>
6<h1>Greenstone Manual Information</h1>
10<li><a href="#requirements">Requirements</a></li>
11<li><a href="#contents">Contents of this package</a></li>
12<li><a href="#file-structure">File structure</a></li>
13<li><a href="#include-gli-help">Including GLI Help in the User Guide</a></li>
14<li><a href="#generate-html">Generating HTML files</a></li>
15<li><a href="#pdf">Generataing PDF files</a></li>
16<li><a href="#status">Current status of the manuals</a></li>
17<li><a href="#format">The XML Format</a></li>
18<li><a href="#languages">Translate into other langauges</a></li>
19<li><a href="#todo">ToDo list</a></li>
22<a name="requirements"/>
24<p>To use this package to re-generate the Greenstone tutorial HTML, or generate a workshop, you need to have the following:</p>
26<li>Greenstone version 2.71 installed</li>
27<li>A Java runtime system</li>
30<a name="contents"/>
31<h2>Contents of this package</h2>
33<dt>README.html</dt><dd>This file</dd>
34<dt>xml-source directory</dt><dd>Contains all the XML source files and images.
35Any changes to the Manuals should be made to the source files in this directory.
36The xml-source directory contains:
38<li>en, es, fr, ru subdirectories, which hold the source files for English,
39Spanish, French and Russian respectively. Each subdirectory contains 4 XML files
40and an images subdirectory. The 4 XML files correspond to the 4 Greenstone
41manuals: Develop's manual, Installer's manual, User's manual, and From Paper to
42Collection manual. The images directory contains all the images for every
44<p><b>Note:</b> The en folder for English is the primary one. Any changes should
45be made to this folder and let the translator take care of other languages.</p>
46<li>manual.dtd: the DTD with the XML files</li>
49<dt>processing directory</dt><dd>Contains all the XSL files and CSS files for
50running XSL transform:
52<li><b>xml-to-top-index.xsl </b>XSL Transform file to generate a top index file
53for all the manuals.</li>
54<li><b>xml-to-index.xsl</b> XSL Transform file to generate an index file for
55individual chapters of one manual.</li>
56<li><b>xml-to-one-html.xsl</b> XSL transform file to generate a single HTML page
57for each manual.</li>
58<li><b>xml-to-many-html.xsl</b> XSL transform file to generate individual HTML
59files for each manual, every chapter is a HTML file.</li>
60<li><b>common.xsl</b> Common XSL templates for use with all transforms.</li>
61<li><b>xml-to-pdf.xsl</b> XSL Transform file to generate a PDF file for every
64<a name="contents"/>
65<li><b>fo-common.xsl</b> Common XSL templates for use with PDF transforms.</li>
66<li><b>crossref-inter.xsl, crossref.xsl, crossref-pdf.xsl</b> XSL files for
67getting the correct link address for links that refer to other chapters,
68sections, footnotes or other manuals. crossref-inter.xsl is used for generating
69multiple HTML files, crossref.xsl for generating a single HTML file, and
70crossref-pdf.xsl for generating PDF file.</li></a>
71<li><b>manifest.xml </b>list of the manuals, used for generate the top index.</li>
72<li><b>pdf-fonts</b> directory holds all the font files for languages whose
73fonts are not included in the base 14 fonts that FOP supports(see
74<a href="">here</a>
75for more).</li>
78<dt></dt><dd>Shell script that generates all the HTML files</dd>
79<dt></dt><dd>Shell script that generates all the PDF files</dd>
80<dt></dt><dd>Shell script that clean all the generated files</dd>
83<a name="file-structure"/>
84<h2>File structure</h2>
85<p>When generate HTML files and PDF files without using the shell scripts, you should:
87<li>First create a <tt>build</tt> subdirectory here if there isn't one.</li>
88<li>For each language, create a subdirectory with the language code (eg. en, fr, es, ru) as the name of the directory, if there isn't one.</li>
89<li>cd to the appropriate direcotry, copy the <tt>images</tt> folder and the <tt>style.css</tt> file here</li>
90<li>Create a <tt>HTML</tt> and a <tt>PDF</tt> subdirectory for the generated HTML and PDF files.</li>
92<p>If you use the shell scripts, they will create the subdirectories for you.</p>
93<p>The file structure of the <tt>build</tt> directory is like this:</p>
96 --build
97 --<i>language-code</i>
98 --html
99 (all the generated html files go here)
100 --pdf
101 (all the generated pdf files go here)
102 --images
103 style.css
106<a name="include-gli-help"/>
107<h2>Including the GLI Help in User Guide</h2>
108<p>The "Librarian Interface user guide" section in the User's Guide manual is generated from the GLI Help, so when GLI Help was updated, this section needs to be regenerated to an XML file under xml-source/language directory. To regenerate the XML file,</p>
110<li>Go to the Greenstone installation directory and run <code>source setup.bash</code></li>
111<li>Go to the <code>gsdl-documentation/shared</code> directory, run <br/>
112<code>java ApplyXSLT ../manuals/processing/gen-gli-help-to-manual-chapter.xsl $GSDLHOME/gli/help/{lang}/help.xml > ../manuals/xml-source/{lang}/help-{lang}.xml</code>
113<p>replace <code>{lang}</code> with a specific language code, for example:</p>
114<code>java ApplyXSLT ../manuals/processing/gen-gli-help-to-manual-chapter.xsl $GSDLHOME/gli/help/en/help.xml > ../manuals/xml-source/en/help-en.xml</code>
117<p>In the XML source file of User's Guide, GLI Help is included by means of defining an ENTITY(chap_gli) in the DTD. For example:</p>
119&lt;!DOCTYPE Manual [
120 &lt;!ENTITY chap_gli SYSTEM "help-en.xml"&gt;
124<a name="generate-html"/>
125<h2>Generating HTML files</h2>
127<li>Run <tt>source setup.bash</tt> in the top level directory of your Greenstone installation</li>
128<li>Create a subdirectory named <tt>build</tt>, if there isn't one. cd to the <tt>build</tt> directory, create a subdirectory named with the <tt>language_code</tt> if there isn't one, for example, en for English language.
129<li>cd to the <tt>language_code</tt> directory, create a <tt>html</tt> subdirectory</li>
130<li>copy the <tt>images</tt> folder and <tt>style.css</tt> file here</li>
132<li>Generate the index page:<br/>
133<tt>java -cp ..:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:../xalan.jar -DGSDLHOME=$GSDLHOME ApplyXSLT ../xml-to-index.xsl <i>manual-name</i>_<i>language-code</i>.xml > html/<i>manual-name</i>_<i>language-code</i>_index.html</tt></li>
134<li>Generate the individual pages<br/>
135<tt>java -cp ..:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:../xalan.jar -DGSDLHOME=$GSDLHOME ApplyXSLT ../xml-to-many-html.xsl ../<i>manual-name</i>_<i>language-code</i>.xml | perl -S $GSDLHOME/gli/help/</tt>
136<p>then move all the generated htm files into the html directory</p>
138<li>Generate a single HTML file<br/>
139<tt>java -cp ..:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:../xalan.jar -DGSDLHOME=$GSDLHOME ApplyXSLT ../xml-to-one-html.xsl ../<i>manual-name</i>_<i>language-code</i>.xml > <i>manual-name</i>_<i>language-code</i>_all.html</tt></li>
142<p>The scripts are shell scripts that carry out a lot of these
143commands for you, we recommend to use this script to generate the HTML pages.</p>
145<a name="pdf"/>
146<h2>Generataing PDF files</h2>
148<li>Run <tt>source setup.bash</tt> in the top level directory of the Greenstone installation</li>
149<li>Unzip the file under <tt>shared</tt> directory</li>
150<li>Generate the PDF file:<br/>
151<tt>export CLASSPATH=$CLASSPATH:../shared/fop/build/fop.jar:../shared/fop/lib</tt><br/>
152<tt>./../shared/fop/ -c ../shared/fop/conf/userconfig.xml -q -xsl processing/xml-to-pdf.xsl -xml xml-source/<i>language-code</i>/<i>manual-name</i>_<i>language-code</i>.xml -pdf build/<i>language-code</i>/pdf/<i>manual-name</i>_<i>language-code</i>.pdf</tt></li>
154<p>The scripts are shell scripts that carry out a lot of these
155commands for you, we recommend you to use </p>
157<a name="status"/>
158<h2>The current status of the manuals</h2>
160<dt>Developer's manual</dt><dd>Greesntone 2.50, translated in Mar. 2004</dd>
161<dt>User's manual</dt><dd>Greenstone 2.70, translated in Mar. 2006</dd>
162<dt>Installer's manual</dt><dd>Greenstone 2.50, translated in Mar. 2004</dd>
163<dt>From Paper to Collection</dt><dd>Greenstone 2.50, translated in Mar. 2004</dd>
166<a name="format"/>
167<h2>The XML Format</h2>
168<p>Develop_en.xml, User_en.xml, Install_en.xml and Paper_en.xml in the en directory are the main files. Make modifications in those. The translator takes care of the other languages.</p>
169<p>All &lt;Text&gt; elements need a unique id, and all need to be on their own lines, with no other tags (apart from tags inside the text).</p>
170<p>All &lt;Chapter&gt;, &lt;Section&gt;, &lt;Subsection&gt;, &lt;Part&gt;, &lt;Table&gt;, &lt;Figure&gt; elements need a unique id.</p>
171<p>See the <a href="xml-source/manual.dtd">DTD</a> file for more information.
173<a name="languages"/>
174<h2>Translate into other languages</h2>
175<p>To tranlate these manuals into other languages, use Greenstone Translator to do this, see <a href="">here</a>.</p>
176<p>The "module-name" for the manuals are devmanual, installmanual, papermanual and usermanual.</p>
177<p>For languages whose fonts are not included in the base 14 fonts that FOP
178supports, eg. Russian, new font may be required to install before generating PDF
179files in these languages. Install a new language to FOP have 3 steps:</p>
181 <li>Find an appropriate font file (in .PFM or .TTF format) that contains the
182 necessary fonts;</li>
183 <li>Go to the FOP installation, and run TTFReader to
184 generate an XML file for the font, eg. <br/>
185 <blockquote>
186 <p><code><font size="2">java -cp .:/research/lh92/greenstone/documentation/modules/shared/fop/build/fop.jar:/research/lh92/greenstone/documentation/modules/shared/fop/lib/avalon-framework.jar:/research/lh92/greenstone/documentation/modules/shared/fop/lib/xml-apis.jar:/research/lh92/greenstone/documentation/modules/shared/fop/lib/xercesImpl.jar:/research/lh92/greenstone/documentation/modules/shared/fop/lib/xalan.jar org.apache.fop.fonts.apps.TTFReader /research/lh92/packages/fonts/ae_Arab.ttf /research/lh92/greenstone/documentation/modules/shared/fop/conf/Arab.xml</font></code></p>
187 </blockquote>
188 </li>
189 <li>Register to FOP by adding a new entry in the userconfig.xml file, see below for an example</li>
190 <li>In fo-common.xsl, add a new language-value pair for the <code>font</code> variable, and make sure the <code>lang</code> attribute in the source xml file is set properly.</li>
194<p>For example, for the Russian language, the <code>L_10646.TTF</code>(under
195Windows) TrueType Font file contains the required Cyrillic font, then run</p>
197 <p><code><font size="2">java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;lib\xercesImpl.jar;lib\xalan.jar
198 org.apache.fop.fonts.apps.TTFReader [options] L_10646.TTF Cyrillic.xml</font></code></p>
200<p>to generate the font xml configure file <code>Cyrillic.xml</code>.</p>
201<p>Then go to the <code>conf</code> directory under fop installation directory,
202open <code>userconfig.xml</code> file, in <code>&lt;fonts&gt;</code> element, add</p>
204 <p><code><font size="2">&lt;font metrics-file=&quot;//research/lh92/gsdl-documentation/shared/fop/conf/Cyrillic.xml&quot;
205 kerning=&quot;yes&quot; embed-file=&quot;//research/lh92/gsdl-documentation/shared/fop/conf/L_10646.TTF&quot;&gt;<br>
206&nbsp; &lt;font-triplet name=&quot;Cyrillic&quot; style=&quot;normal&quot; weight=&quot;normal&quot;/&gt;<br>
207&nbsp; &lt;font-triplet name=&quot;Cyrillic&quot; style=&quot;normal&quot; weight=&quot;bold&quot;/&gt;<br>
208&nbsp; &lt;font-triplet name=&quot;Cyrillic&quot; style=&quot;italic&quot; weight=&quot;normal&quot;/&gt;<br>
209&nbsp; &lt;font-triplet name=&quot;Cyrillic&quot; style=&quot;italic&quot; weight=&quot;bold&quot;/&gt;<br>
210 &lt;/font&gt;</font></code></p>
212<p>Then run fop with <code>-c userconfig.xml</code> option to use the new
213configuration. Preferably, use the generate-pdf script because this already
214uses the option.</p>
215<p>Note: when you see the <code>[Fatal Error] :1:1: Content is not allowed in prolog</code> exception, please check
216whether the filepaths of the configuration file (xml) and the font file (.ttf) are correct.</p>
219<a name="todo"/>
220<h2>ToDo list</h2>
222<li>Windows scripts<li>Automatic texts<p>Texts like button names should be automatic generated, like in greenstone tutorials, but currently we didn't do this because the manuals are supposed to be rewritten soon, but this shall be done after the reversion.</p></li>
223<li>PDF fonts (done, but for new languages still needs to find an appropriate
224font set)<p>The XML to PDF transform require for a correct font set for a
225specific language.</p></li>
226<li>Images in PDF files<p>Images should not be too long, otherwise cannot
227generate the PDF file.</p></li>
228<li>Navigation buttons (done)<p>Add navigation buttons in the html pages.</p></li>
Note: See TracBrowser for help on using the repository browser.