source: trunk/gsdl-documentation/manuals/README.html@ 13645

Last change on this file since 13645 was 13645, checked in by lh92, 17 years ago

readme file for the manuals package
  • Property svn:keywords set to Author Date Id Revision
File size: 8.1 KB
Line 
1<html>
2<head>
3<title>Greenstone Manuals</title>
4</head>
5<body>
6<h1>Greenstone Manual Information</h1>
7
8<h2>Contents</h2>
9<ul>
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="#generate-html">Generating HTML files</a></li>
14<li><a href="#pdf">Generataing PDF files</a></li>
15<li><a href="#status">Current status of the manuals</a></li>
16<li><a href="#format">The XML Format</a></li>
17<li><a href="#languages">Translate into other langauges</a></li>
18<li><a href="#todo">ToDo list</a></li>
19</ul>
20
21<a name="requirements"/>
22<h2>Requirements</h2>
23<p>To use this package to re-generate the Greenstone tutorial HTML, or generate a workshop, you need to have the following:</p>
24<ul>
25<li>Greenstone version 2.71 installed</li>
26<li>A Java runtime system</li>
27</ul>
28
29<a name="contents"/>
30<h2>Contents of this package</h2>
31<dl>
32<dt>README.html</dt><dd>This file</dd>
33<dt>xml-source directory</dt><dd>Contains all the XML source files and images. Any changes to the Manuals should be made to the source files in this directory. The xml-source directory contains:
34<ul>
35<li>en, es, fr, ru subdirectories, which hold the source files for English, Spanish, French and Russian respectively. Each subdirectory contains 4 XML files and an images subdirectory. The 4 XML files correspond to the 4 Greenstone manuals: Develop's manual, Installer's manual, User's manual, and From Paper to Collection manual. The images directory contains all the images for every manual.</li>
36<p><b>Note:</b> The en folder for English is the primary one. Any changes should be made to this folder and let the translator take care of other languages.</p>
37<li>manual.dtd: the DTD with the XML files</li>
38</ul>
39</dd>
40<dt>processing directory</dt><dd>Contains all the XSL files and CSS files for running XSL transform:
41<ul>
42<li><b>common.xsl</b> Common XSL templates for use with all transforms.</li>
43<li><b>xml-to-one-html.xsl</b> XSL transform file to generate a single HTML page for each manual.</li>
44<li><b>xml-to-many-html.xsl</b> XSL transform file to generate individual HTML files for each manual, every chapter is a HTML file.</li>
45<li><b>xml-to-index.xsl</b> XSL Transform file to generate an index file for individual chapters of one manual.</li>
46<li><b>xml-to-pdf.xsl</b> XSL Transform file to generate a PDF file for every manual.</li>
47<li><b>fo-common.xsl</b> Common XSL templates for use with PDF transforms.</li>
48<li><b>crossref-inter.xsl, crossref.xsl, crossref-pdf.xsl</b> XSL files for getting the correct link address for links that refer to other chapters, sections, footnotes or other manuals. crossref-inter.xsl is used for generating multiple HTML files, crossref.xsl for generating a single HTML file, and crossref-pdf.xsl for generating PDF file.</li>
49</ul>
50</dd>
51<dt>generate-html.sh</dt><dd>Shell script that generates all the HTML files</dd>
52<dt>generate-pdf.sh</dt><dd>Shell script that generates all the PDF files</dd>
53<dt>clean-all.sh</dt><dd>Shell script that clean all the generated files</dd>
54</dl>
55
56<a name="file-structure"/>
57<h2>File structure</h2>
58<p>When generate HTML files and PDF files without using the shell scripts, you should:
59<ol>
60<li>First create a <tt>build</tt> subdirectory here if there isn't one.</li>
61<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>
62<li>cd to the appropriate direcotry, copy the <tt>images</tt> folder and the <tt>style.css</tt> file here</li>
63<li>Create a <tt>HTML</tt> and a <tt>PDF</tt> subdirectory for the generated HTML and PDF files.</li>
64</ol>
65<p>If you use the shell scripts, they will create the subdirectories for you.</p>
66<p>The file structure of the <tt>build</tt> directory is like this:</p>
67<pre>
68--manuals
69 --build
70 --<i>language-code</i>
71 --html
72 (all the generated html files)
73 --pdf
74 (all the generated pdf files)
75 --images
76 style.css
77</pre>
78
79<a name="generate-html"/>
80<h2>Generating HTML files</h2>
81<ol>
82<li>Run <tt>source setup.bash</tt> in the top level directory of your Greenstone installation</li>
83<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.
84<li>cd to the <tt>language_code</tt> directory, create a <tt>html</tt> subdirectory</li>
85<li>copy the <tt>images</tt> folder and <tt>style.css</tt> file here</li>
86<!--
87<li>Generate the index page:<br/>
88<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>
89<li>Generate the individual pages<br/>
90<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/splithelpdocument.pl</tt>
91<p>then move all the generated htm files into the html directory</p>
92</li>
93<li>Generate a single HTML file<br/>
94<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>
95-->
96</ol>
97<p>The generate-html.sh scripts are shell scripts that carry out a lot of these commands for you.</p>
98
99<a name="pdf"/>
100<h2>Generataing PDF files</h2>
101<ol>
102<li>Run <tt>source setup.bash</tt> in the top level directory of the Greenstone installation</li>
103<li>Unzip the fop.zip file under <tt>shared</tt> directory</li>
104<li>Generate the PDF file:<br/>
105<tt>export CLASSPATH=$CLASSPATH:../shared/fop/build/fop.jar:../shared/fop/lib</tt><br/>
106<tt>./../shared/fop/fop.sh -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>
107</ol>
108<p>The generate-pdf.sh scripts are shell scripts that carry out a lot of these commands for you.</p>
109
110<a name="status"/>
111<h2>The current status of the manuals</h2>
112<dl>
113<dt>Developer's manual</dt><dd>Greesntone 2.50, translated in Mar. 2004</dd>
114<dt>User's manual</dt><dd>Greenstone 2.70, translated in Mar. 2006</dd>
115<dt>Installer's manual</dt><dd>Greenstone 2.50, translated in Mar. 2004</dd>
116<dt>From Paper to Collection</dt><dd>Greenstone 2.50, translated in Mar. 2004</dd>
117</dl>
118
119<a name="format"/>
120<h2>The XML Format</h2>
121<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>
122<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>
123<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>
124<p>See the <a href="xml-source/manual.dtd">DTD</a> file for more information.
125
126<a name="languages"/>
127<h2>Translate into other languages</h2>
128<p>To tranlate these manuals into other languages, use Greenstone Translator to do this, see <a href="http://wesson.cs.waikato.ac.nz:7070/wiki/index.php/GTI">here</a>.</p>
129<p>The "module-name" for the manuals are devmanual, installmanual, papermanual and usermanual.</p>
130
131<a name="todo"/>
132<h2>Known problems and TODO list</h2>
133<ol>
134<li>Automatic texts<dd>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.</dd></li>
135<li>PDF fonts<dd>The XML to PDF transform require for a correct font set for a specific language.</dd></li>
136<li>Images in PDF files<dd>Sometimes when images contain unusual fonts and characters, the conversion of the XML to PDF might broke down.</dd></li>
137<li>Navigation buttons<dd>Add navigation buttons in the html pages.</dd></li>
138</ol>
139</body>
140</html>
Note: See TracBrowser for help on using the repository browser.