source: documentation/trunk/tutorials/README.html

Last change on this file was 33782, checked in by kjdon, 4 years ago

updated README

  • Property svn:keywords set to Author Date Id Revision
File size: 16.4 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4 <title>Greenstone tutorials.</title>
5</head>
6<body>
7<h1>Greenstone Tutorial Information</h1>
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="#generate-html">Generating HTML files</a></li>
13 <li><a href="#languages">Generating files for other langauges</a></li>
14 <li><a href="#workshop">Generataing a workshop</a></li>
15 <li><a href="#format">Tutorial XML Format</a></li>
16 <li><a href="#print">Notes for printing</a></li>
17</ul>
18<a name="requirements">
19</a>
20<h2>Requirements</h2>
21To use this package to re-generate the
22Greenstone tutorial HTML, or generate a workshop, you need to have the
23following:
24
25<ul>
26 <li>Greenstone version 2.87/3.09 installed</li>
27 <li>A Java runtime system</li>
28</ul>
29<a name="contents">
30</a>
31<h2>Contents of this package</h2>
32<dl>
33 <dt><b>README.html</b></dt><dd>This file</dd>
34 <dt><b>generate-html.sh/bat</b></dt><dd>Scripts for generating all the HTML</dd>
35 <dt><b>generate-workshop.sh/bat</b></dt><dd>Scripts for generating a workshop</dd>
36 <dt><b>xml-source</b></dt><dd>The raw XML files for the tutorials
37 <ul>
38<li><b>tutorial_en.xml</b> The main tutorial XML file, in English. Valid for 2.87/3.09</li>
39<li><b>tutorial_[fr|ru|es].xml</b> Translations (of an old version) of tutorial_en.xml. Valid for 2.70</li>
40</ul>
41</dd>
42<dt><b>processing</b></dt><dd>XSL and auxiliary files for transforming the XML into HTML or other format
43<ul>
44<li><b>common.xsl</b> Common XSL templates for use with all transforms</li>
45<li><b>xml-to-one-html.xsl</b> XSL Transform file to generate a single HTML page containing all tutorials</li>
46<li><b>xml-to-index.xsl</b> XSL Transform file to generate an index file for individual tutorial HTML files</li>
47<li><b>xml-to-many-html.xsl</b> XSL Transform file to generate individual HTML files for each tutorial</li>
48<li><b>xml-to-one-workshop.xsl</b> XSL Transform file to generate a single HTML file for a workshop. Uses the manifest.xml</li>
49<li><b>xml-to-workshop.xsl</b> XSL Transform file to generate a series of HTML files for a workshop, one per session. Uses the manifest.xml</li>
50<li><b>xml-to-top-index.xsl</b> XSL Transform file to generate a top level index file linking to all four language versions</li>
51<li><b>xml-to-wiki-index.xsl</b> XSL Transform file to generate wiki syntax for an index on the Greenstone wiki</li>
52<li><b>manifest.xml</b> Sample manifest file for workshop generation</li>
53</ul></dd>
54<dt><b>../shared</b></dt><dd>Java classes and jar files common to tutorials and manuals
55<ul>
56<li><b>Dictionary.java</b> Java class for retrieving text strings based on keys from GLI dictionary, Perl dictionary, macro files</li>
57<li><b>ApplyXSLT.java</b> Java class for running the XSL transforms. I couldn't just use Xalan because the Java extensions (using Dictionary) didn't work.</li>
58<li><b>xalan.jar</b> XSLT transformer needed for use with Java 1.5. Java 1.4 comes with Xalan, Java 1.5 comes with XSLTC.</li>
59</ul></dd>
60</dl>
61<a name="generate-html">
62</a>
63<h2>Generating HTML files</h2>
64<h3>The easy way</h3>
65<ol>
66 <li>Run <tt>source setup.bash/source gs3-setup.sh</tt> in the
67top level directory of your Greenstone installation</a></li>
68 <li>Run <tt>./generate-html.sh [2 or 3]</tt> in this tutorials directory, where 2/3 is which Greenstone version you want to generate tutorials for. </li>
69</ol>
70Windows versions of these commands are like the
71following:
72<ol>
73 <li><tt>setup.bat/gs3-setup.bat</tt> in the top level directory of your gs2 or gs3 installation</li>
74 <li><tt>generate-html [2 or 3]</tt> in this tutorials directory</li>
75</ol>
76
77These commands will make an html folder, with en subfolder containing all the English pages, plus index.html and wiki-index.txt.
78
79This is currently set up to only generate the English version of the HTML. The French, Spanish and Russion translations are for 2.70 and haven't been updated, so we don't need to do them each time. But if they did get translated, and you want to generate the other languages, do the following:
80<ol>
81 <li>Edit generate-html.sh, and add all the language codes to langs (langs="en fr es ru")</li>
82 <li>Edit xml-to-top-index.xsl, set the value of all-langs variable to 1</li>
83 <li>Re-run the generate-html.sh/bat script</li>
84</ol>
85
86<h3>The old complicated way</h3>
87<ol>
88 <li>Run <tt>source setup.bash</tt> in the
89 top level directory of your Greenstone installation</li>
90 <li><a name="generate-html">Create a subdirectory in gsdl-tutorials
91for your output files. If you are using multiple languages and want to
92create top level index files, then you should name the directories en,
93fr, es, and ru, otherwise the links won't be valid.</a></li>
94 <li><a name="generate-html">cd to the appropriate directory</a></li>
95 <li><a name="generate-html">Generate the index page:<br>
96 <tt>java -cp
97$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
98-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-index.xsl
99$source_dir/tutorial_$l.xml &gt; index.html</tt></a></li>
100 <li><a name="generate-html">Generate the individual pages<br>
101 <tt>java -cp
102$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
103-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-many-html.xsl
104$source_dir/tutorial_$l.xml | perl -S
105$GSDLHOME/gli/help/splithelpdocument.pl</tt></a></li>
106 <li><a name="generate-html">Generate a single HTML file containing
107all tutorials<br>
108 <tt>java -cp
109$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
110-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-one-html.xsl
111$source_dir/tutorial_$l.xml &gt; all_tutorials.html</tt></a></li>
112 <li><a name="generate-html">Generate the top level combined index.
113Should be run from the gsdl-tutorial directory, not from the
114subdirectory<br>
115 <tt>java -cp
116$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
117-DGSDLHOME=$GSDLHOME ApplyXSLT
118$processing_dir/xml-to-top-index.xsl&nbsp; $source_dir/tutorial_en.xml
119&gt; $output_dir/index.html</tt></a></li>
120</ol>
121<a name="generate-html">Windows versions of these commands are like the
122following:
123</a>
124<ol>
125 <li><a name="generate-html">Run <tt>setup</tt> in the top level
126directory of your Greenstone installation</a></li>
127 <li><a name="generate-html">Create a subdirectory in gsdl-tutorials
128for your output files. If you are using multiple languages and want to
129create top level index files, then you should name the directories en,
130fr, es, and ru, otherwise the links won't be valid.</a></li>
131 <li><a name="generate-html">cd to the appropriate directory</a></li>
132 <li><a name="generate-html">Generate the index page:<br>
133 <tt>java -cp
134%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar
135-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-index.xsl
136%source_dir%\tutorial_en.xml &gt; index.html</tt></a></li>
137 <li><a name="generate-html">Generate the individual pages<br>
138 <tt>java -cp
139%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar
140-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-many-html.xsl
141%source_dir%\tutorial_en.xml | perl -S
142%GSDLHOME%\gli\help\splithelpdocument.pl<br>
143 <br>
144 </tt></a></li>
145 <li><a name="generate-html">Generate a single HTML file containing
146all tutorials<br>
147 <tt>java -cp
148%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar
149-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-one-html.xsl
150%source_dir%\tutorial_en.xml &gt; all_tutorials.html<br>
151 <br>
152 </tt></a></li>
153 <li><a name="generate-html">Generate the top level combined index.
154Should be run from the gsdl-tutorial directory, not from the
155subdirectory<br>
156 <tt>java -cp
157%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar
158-DGSDLHOME=%GSDLHOME% ApplyXSLT
159%processing_dir%\xml-to-top-index.xsl&nbsp;
160%source_dir%\tutorial_en.xml &gt; %output_dir%\index.html<br>
161 <br>
162 </tt></a></li>
163</ol>
164<p><a name="generate-html">The generate-html.sh/bat scripts are shell
165scripts that carry out a lot of these commands for you.</a></p>
166<a name="generate-html"> </a><a name="languages">
167</a>
168<h2><a name="languages">Generating files for other languages</a></h2>
169<p><a name="languages">The English version of the tutorial is currently
170valid for Greenstone 2.85, while the French, Spanish and Russian
171versions are valid for Greenstone version 2.70. If you want to generate
172a workshop using one of these languages, you will need to use
173Greenstone 2.70. </a></p>
174<p><a name="languages">You will need to replace the appropriate source
175file name for tutorial_en.xml in the above commands. Edit common.xsl,
176and change 'en' to e.g. 'fr' in the line</a></p>
177<a name="languages"><tt>&lt;xsl:variable name="diction"
178select="dict:new('en')"/&gt;</tt>
179</a>
180<p><a name="languages">If you want an up-to-date tutorial for another
181language, one option is to have the tutorial text in English, with all
182the button names and GLI references in the other language. To do this,
183use tutorial_en.xml as the source file, but change the dictionary
184language as above.</a></p>
185<a name="workshop">
186</a>
187<h2><a name="workshop">Generating the exercises for a workshop</a></h2>
188<p><a name="workshop">For a workshop, you can select a subset of the
189exercises, and place them in any order you want. This is done with the
190manifest file. A sample manifest file has been included - this is one
191that we used for a Greenstone workshop in Hawaii, 2006.</a></p>
192<p><a name="workshop">Once you have created your manifest file, you
193need to run the following. You can choose whether to have a separate
194HTML file per session, or the entire workshop in one file.</a></p>
195<ol>
196 <li><a name="workshop">Run <tt>source setup.bash</tt> in the top
197level directory of your Greenstone installation</a></li>
198 <li><a name="workshop">Create a subdirectory in gsdl-tutorials for
199your output files, eg "workshop"</a></li>
200 <li><a name="workshop">cd to this directory</a></li>
201 <li><a name="workshop">Generate one file per workshop session:<br>
202 <tt>java -cp
203$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
204-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-workshop.xsl
205$source_dir/tutorial_en.xml | perl -S
206$GSDLHOME/gli/help/splithelpdocument.pl</tt></a></li>
207 <li><a name="workshop">Generate a single file containing all sessions<br>
208 <tt>java -cp
209$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
210-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-one-workshop.xsl
211$source_dir/tutorial_en.xml &gt; workshop.html</tt></a></li>
212</ol>
213<a name="workshop">Windows versions of these commands are like:
214</a>
215<ol>
216 <li><a name="workshop">Run <tt>setup</tt> in the top level directory
217of your Greenstone installation</a></li>
218 <li><a name="workshop">Create a subdirectory in gsdl-tutorials for
219your output files, eg "workshop"</a></li>
220 <li><a name="workshop">cd to this directory</a></li>
221 <li><a name="workshop">Generate one file per workshop session:<br>
222 <tt>java -cp
223"%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar"
224-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-workshop.xsl
225%source_dir%\tutorial_en.xml | perl -S
226"%GSDLHOME%\gli\help\splithelpdocument.pl"<br>
227 <br>
228 </tt></a></li>
229 <li><a name="workshop">Generate a single file containing all sessions<br>
230 <tt>java -cp
231"%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar"
232-DGSDLHOME=%GSDLHOME% ApplyXSLT
233%processing_dir%\xml-to-one-workshop.xsl %source_dir%\tutorial_en.xml
234&gt; workshop.html<br>
235 <br>
236 </tt></a></li>
237</ol>
238<p><a name="workshop">The generate-workshop.sh/bat scripts are shell
239scripts that carry out these commands for you.</a></p>
240<p><a name="workshop">A basic manifest file looks something like this:
241</a></p>
242<pre><a name="workshop">&lt;Manifest&gt;<br> &lt;Title&gt;Greenstone Hawaii Workshop, Jun 2006&lt;/Title&gt;<br> &lt;Section id="one" number="1"&gt;<br> &lt;Heading&gt;Lab 1: Installing Greenstone&lt;/Heading&gt;<br> &lt;TutorialRef id="install_greenstone"/&gt;<br> &lt;TutorialRef id="update_greenstone_installation"/&gt;<br> &lt;/Section&gt;<br> &lt;Section id="two" number="2"&gt;<br> &lt;Heading&gt;Lab 2: Building a collection&lt;/Heading&gt;<br> &lt;TutorialRef id="small_html_collection"/&gt;<br> &lt;TutorialRef id="word_pdf_collection"/&gt;<br> &lt;/Section&gt;<br>&lt;/Manifest&gt;<br></a></pre>
243<p><a name="workshop">The manifest has a <b>Title</b>, which is the
244Workshop title. Then it is divided into <b>Section</b>s. Each section
245will be saved in a separate file, named using the Section's <b>id</b>
246attribute. A Section has a <b>Heading</b>, and then a list of <b>TutorialRef</b>s
247- these indicate which tutorials should go into the section. The <b>id</b>
248attribute must match the Tutorial id used in tutorial_en.xml.</a></p>
249<a name="workshop">For more control over the exercises, you can specify
250only part of a tutorial should be used in one exercise.
251For example, in the Hawaii workshop, we split the Word and PDF exercise
252over two lab sessions. To do this we used &lt;SplitTutorialRef&gt;.
253</a>
254<pre><a name="workshop">&lt;SplitTutorialRef id="word_pdf_collection" titleextra="&#8212;Part A" type="preceding" split="Heading[2]"&gt;<br>&lt;EndNotes&gt;<br>&lt;Comment&gt;&lt;Text&gt;In exercise 2.1 we correct some of this incorrect metadata by manually adding Dublin Core Title metadata.&lt;/Text&gt;&lt;/Comment&gt;<br>&lt;/EndNotes&gt;<br>&lt;/SplitTutorialRef&gt;<br>....<br>&lt;SplitTutorialRef id="word_pdf_collection" titleextra="&#8212;Part B" type="following" current="true" split="Heading[2]"&gt;<br>&lt;BeginNotes&gt;<br>&lt;Comment&gt;&lt;Text&gt;In the Librarian Interface, open up the reports collection that you created in exercise 1.5. Remember that the extracted Title metadata for some documents was incorrect.&lt;/Text&gt;&lt;/Comment&gt;<br>&lt;/BeginNotes&gt;<br>&lt;/SplitTutorialRef&gt;<br></a></pre>
255<p><a name="workshop"><b>SplitTutorialRef</b> has some extra attributes:<br>
256<b>titleextra</b>: some extra text to be added to the Title, in this
257case, we add "&#8212; Part A" and "&#8212; Part B".<br>
258<b>split</b>: the XML node to split the tutorial on.<br>
259<b>type</b>: whether we want the sections before the split (preceeding)
260or after the split (following).<br>
261<b>current</b>: set to true if the node to split on should be included.
262</a></p>
263<p><a name="workshop"><b>SplitTutorialRef</b> can also include <b>BeginNotes</b>
264and/or <b>EndNotes</b> element - this is for extra text of
265instructions that should be added to the start or end of the exercise.
266The format inside BeginNotes and EndNotes follows the format of the
267general tutorial, see below.</a></p>
268<a name="format">
269</a>
270<h2><a name="format">Tutorial XML Format</a></h2>
271<p><a name="format">tutorial_en.xml is the main file. Make
272modifications in that. The translator takes care of the other languages.</a></p>
273<p><a name="format">All &lt;Text&gt; elements need a unique id, and all
274need to be on their own lines, with no other tags (apart from tags
275inside the text).</a></p>
276<p><a name="format">Tag examples:<br>
277<br>
278<tt>&lt;Link&gt;url&lt;/Link&gt;</tt> for URLS.<br>
279<tt>&lt;Link url="url"&gt;display text&lt;/Link&gt;</tt> for URLS which
280have different text to display<br>
281<tt>&lt;Format&gt;format statement, or macro statement&lt;/Format&gt;</tt><br>
282<tt>&lt;Path&gt;file paths&lt;/Path&gt;</tt><br>
283<tt>&lt;Menu&gt; menu sequence, eg File &#8594; New&lt;/Menu&gt;</tt><br>
284</a></p>
285<p><a name="format">Bullet lists:
286</a></p>
287<pre><a name="format">&lt;BulletList&gt;<br> &lt;Bullet&gt;<br> &lt;Text id="223"&gt;first bullet point&lt;/Text&gt;<br> &lt;/Bullet&gt;<br> ...<br>&lt;/BulletList&gt;<br></a></pre>
288<p></p>
289<a name="format">Main numbering
290</a>
291<pre><a name="format">&lt;NumberedItem&gt;<br> text, comments etc go in here <br>&lt;/NumberedItem&gt;<br></a></pre>
292<a name="format">Block of text in italics:
293</a>
294<pre><a name="format">&lt;Comment&gt;<br> &lt;Text id="xxx"&gt;some italics text&lt;/Text&gt;<br>&lt;/Comment&gt;<br></a></pre>
295<a name="format">Section heading:
296</a>
297<pre><a name="format">&lt;Heading&gt;<br> &lt;Text id="009"&gt;A heading&lt;/Text&gt;<br>&lt;/Heading&gt;<br></a></pre>
298<a name="print">
299</a>
300<h2><a name="print">Tutorial printing notes</a></h2>
301<a name="print">To print the tutorials with appropriate highlighting in
302place, need to set "print background colours" in page setup (mozilla).
303</a>
304</body>
305</html>
Note: See TracBrowser for help on using the repository browser.