source: trunk/gsdl-documentation/tutorials/README.html@ 13745

Last change on this file since 13745 was 13745, checked in by qq6, 17 years ago

update some linesREADME.html

  • Property svn:keywords set to Author Date Id Revision
File size: 15.7 KB
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <title>Greenstone tutorials.</title>
7<h1>Greenstone Tutorial 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="#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>
18<a name="requirements">
20<h2><a name="requirements">Requirements</a></h2>
21<a name="requirements">To use this package to re-generate the
22Greenstone tutorial HTML, or generate a workshop, you need to have the
26 <li><a name="requirements">Greenstone version 2.71 installed</a></li>
27 <li><a name="requirements">A Java runtime system</a></li>
29<a name="contents">
31<h2><a name="contents">Contents of this package</a></h2>
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
37for 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
40tutorial_en.xml. Valid for 2.70 </a></dd>
41 <dt><a name="contents"></a></dt>
42 <dd><a name="contents">Java class for retrieving text strings based
43on keys from GLI dictionary, Perl dictionary, macro files </a></dd>
44 <dt><br>
45 </dt>
46 <dt><a name="contents"></a></dt>
47 <dd><a name="contents">Java class for running the XSL transforms. I
48couldn't just use Xalan because the Java extensions (using Dictionary)
49didn'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
52transforms </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
55page 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
58for 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
61files 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
64file 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
67HTML 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
70index 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
73an 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.
78Java 1.4 comes with Xalan, Java 1.5 comes with XSLTC. </a></dd>
80<a name="generate-html">
82<h2><a name="generate-html">Generating HTML files</a></h2>
84 <li><a name="generate-html">Run <tt>source setup.bash</tt> in the
85top level directory of your Greenstone installation</a></li>
86 <li><a name="generate-html">Create a subdirectory in gsdl-tutorials
87for your output files. If you are using multiple languages and want to
88create top level index files, then you should name the directories en,
89fr, 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
94-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-index.xsl
95$source_dir/tutorial_$l.xml &gt; index.html</tt></a></li>
96 <li><a name="generate-html">Generate the individual pages<br>
97 <tt>java -cp
99-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-many-html.xsl
100$source_dir/tutorial_$l.xml | perl -S
102 <li><a name="generate-html">Generate a single HTML file containing
103all tutorials<br>
104 <tt>java -cp
106-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-one-html.xsl
107$source_dir/tutorial_$l.xml &gt; all_tutorials.html</tt></a></li>
108 <li><a name="generate-html">Generate the top level combined index.
109Should be run from the gsdl-tutorial directory, not from the
111 <tt>java -cp
114$processing_dir/xml-to-top-index.xsl&nbsp; $source_dir/tutorial_en.xml
115&gt; $output_dir/index.html</tt></a></li>
117<a name="generate-html">Windows versions of these commands are like the
121 <li><a name="generate-html">Run <tt>setup</tt> in the top level
122directory of your Greenstone installation</a></li>
123 <li><a name="generate-html">Create a subdirectory in gsdl-tutorials
124for your output files. If you are using multiple languages and want to
125create top level index files, then you should name the directories en,
126fr, 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
131-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-index.xsl
132%source_dir%\tutorial_en.xml &gt; index.html</tt></a></li>
133 <li><a name="generate-html">Generate the individual pages<br>
134 <tt>java -cp
136-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-many-html.xsl
137%source_dir%\tutorial_en.xml | perl -S
139 <br>
140 </tt></a></li>
141 <li><a name="generate-html">Generate a single HTML file containing
142all tutorials<br>
143 <tt>java -cp
145-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-one-html.xsl
146%source_dir%\tutorial_en.xml &gt; all_tutorials.html<br>
147 <br>
148 </tt></a></li>
149 <li><a name="generate-html">Generate the top level combined index.
150Should be run from the gsdl-tutorial directory, not from the
152 <tt>java -cp
156%source_dir%\tutorial_en.xml &gt; %output_dir%\index.html<br>
157 <br>
158 </tt></a></li>
160<p><a name="generate-html">The scripts are shell
161scripts that carry out a lot of these commands for you.</a></p>
162<a name="generate-html"> </a><a name="languages">
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
166valid for Greenstone 2.71, while the French, Spanish and Russian
167versions are valid for Greenstone version 2.70. If you want to generate
168a workshop using one of these languages, you will need to use
169Greenstone 2.70. </a></p>
170<p><a name="languages">You will need to replace the appropriate source
171file name for tutorial_en.xml in the above commands. Edit common.xsl,
172and change 'en' to e.g. 'fr' in the line</a></p>
173<a name="languages"><tt>&lt;xsl:variable name="diction"
176<p><a name="languages">If you want an up-to-date tutorial for another
177language, one option is to have the tutorial text in English, with all
178the button names and GLI references in the other language. To do this,
179use tutorial_en.xml as the source file, but change the dictionary
180language as above.</a></p>
181<a name="workshop">
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
185exercises, and place them in any order you want. This is done with the
186manifest file. A sample manifest file has been included - this is one
187that we used for a Greenstone workshop in Hawaii, 2006.</a></p>
188<p><a name="workshop">Once you have created your manifest file, you
189need to run the following. You can choose whether to have a separate
190HTML file per session, or the entire workshop in one file.</a></p>
192 <li><a name="workshop">Run <tt>source setup.bash</tt> in the top
193level directory of your Greenstone installation</a></li>
194 <li><a name="workshop">Create a subdirectory in gsdl-tutorials for
195your 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
200-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-workshop.xsl
201$source_dir/tutorial_en.xml | perl -S
203 <li><a name="workshop">Generate a single file containing all sessions<br>
204 <tt>java -cp
206-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-one-workshop.xsl
207$source_dir/tutorial_en.xml &gt; workshop.html</tt></a></li>
209<a name="workshop">Windows versions of these commands are like:
212 <li><a name="workshop">Run <tt>setup</tt> in the top level directory
213of your Greenstone installation</a></li>
214 <li><a name="workshop">Create a subdirectory in gsdl-tutorials for
215your 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
220-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-workshop.xsl
221%source_dir%\tutorial_en.xml | perl -S
223 <br>
224 </tt></a></li>
225 <li><a name="workshop">Generate a single file containing all sessions<br>
226 <tt>java -cp
229%processing_dir%\xml-to-one-workshop.xsl %source_dir%\tutorial_en.xml
230&gt; workshop.html<br>
231 <br>
232 </tt></a></li>
234<p><a name="workshop">The scripts are shell
235scripts that carry out these commands for you.</a></p>
236<p><a name="workshop">A basic manifest file looks something like this:
238<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>
239<p><a name="workshop">The manifest has a <b>Title</b>, which is the
240Workshop title. Then it is divided into <b>Section</b>s. Each section
241will be saved in a separate file, named using the Section's <b>id</b>
242attribute. 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>
244attribute 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
246only part of a tutorial should be used in one exercise.
247For example, in the Hawaii workshop, we split the Word and PDF exercise
248over two lab sessions. To do this we used &lt;SplitTutorialRef&gt;.
250<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>
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
253case, we add "&#8212; Part A" and "&#8212; 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)
256or after the split (following).<br>
257<b>current</b>: set to true if the node to split on should be included.
259<p><a name="workshop"><b>SplitTutorialRef</b> can also include <b>BeginNotes</b>
260and/or <b>EndNotes</b> element - this is for extra text of
261instructions that should be added to the start or end of the exercise.
262The format inside BeginNotes and EndNotes follows the format of the
263general tutorial, see below.</a></p>
264<a name="format">
266<h2><a name="format">Tutorial XML Format</a></h2>
267<p><a name="format">tutorial_en.xml is the main file. Make
268modifications in that. The translator takes care of the other languages.</a></p>
269<p><a name="format">All &lt;Text&gt; elements need a unique id, and all
270need to be on their own lines, with no other tags (apart from tags
271inside the text).</a></p>
272<p><a name="format">Tag examples:<br>
274<tt>&lt;Link&gt;url&lt;/Link&gt;</tt> for URLS.<br>
275<tt>&lt;Link url="url"&gt;display text&lt;/Link&gt;</tt> for URLS which
276have different text to display<br>
277<tt>&lt;Format&gt;format statement, or macro statement&lt;/Format&gt;</tt><br>
278<tt>&lt;Path&gt;file paths&lt;/Path&gt;</tt><br>
279<tt>&lt;Menu&gt; menu sequence, eg File &#8594; New&lt;/Menu&gt;</tt><br>
281<p><a name="format">Bullet lists:
283<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>
285<a name="format">Main numbering
287<pre><a name="format">&lt;NumberedItem&gt;<br> text, comments etc go in here <br>&lt;/NumberedItem&gt;<br></a></pre>
288<a name="format">Block of text in italics:
290<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>
291<a name="format">Section heading:
293<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>
294<a name="print">
296<h2><a name="print">Tutorial printing notes</a></h2>
297<a name="print">To print the tutorials with appropriate highlighting in
298place, need to set "print background colours" in page setup (mozilla).
Note: See TracBrowser for help on using the repository browser.