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