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