| 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><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.71</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.71, 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>
|
|---|
