Greenstone Tutorial Information
Contents
To use this package to re-generate the
Greenstone tutorial HTML, or generate a workshop, you need to have the
following:
- README.html
- This file
- xml-source
- The raw XML files for the tutorials
- tutorial_en.xml The main tutorial XML file, in English. Valid for 2.71
- tutorial_[fr|ru|es].xml Translations (of an old version) of tutorial_en.xml. Valid for 2.70
- processing
- XSL and auxiliary files for transforming the XML into HTMl or other format
- common.xsl Common XSL templates for use with all transforms
- xml-to-one-html.xsl XSL Transform file to generate a single HTML page containing all tutorials
- xml-to-index.xsl XSL Transform file to generate an index file for individual tutorial HTML files
- xml-to-many-html.xsl XSL Transform file to generate individual HTML files for each tutorial
- xml-to-one-workshop.xsl XSL Transform file to generate a single HTML file for a workshop. Uses the manifest.xml
- xml-to-workshop.xsl XSL Transform file to generate a series of HTML files for a workshop, one per session. Uses the manifest.xml
- xml-to-top-index.xsl XSL Transform file to generate a top level index file linking to all four language versions
- xml-to-wiki-index.xsl XSL Transform file to generate wiki syntax for an index on the Greenstone wiki
- manifest.xml Sample manifest file for workshop generation
- ../shared
- Java classes and jar files common to tutorials and manuals
- Dictionary.java Java class for retrieving text strings based on keys from GLI dictionary, Perl dictionary, macro files
- ApplyXSLT.java Java class for running the XSL transforms. I couldn't just use Xalan because the Java extensions (using Dictionary) didn't work.
- xalan.jar XSLT transformer needed for use with Java 1.5. Java 1.4 comes with Xalan, Java 1.5 comes with XSLTC.
- Run source setup.bash in the
top level directory of your Greenstone installation
- Create a subdirectory in gsdl-tutorials
for your output files. If you are using multiple languages and want to
create top level index files, then you should name the directories en,
fr, es, and ru, otherwise the links won't be valid.
- cd to the appropriate directory
- Generate the index page:
java -cp
$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-index.xsl
$source_dir/tutorial_$l.xml > index.html
- Generate the individual pages
java -cp
$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-many-html.xsl
$source_dir/tutorial_$l.xml | perl -S
$GSDLHOME/gli/help/splithelpdocument.pl
- Generate a single HTML file containing
all tutorials
java -cp
$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-one-html.xsl
$source_dir/tutorial_$l.xml > all_tutorials.html
- Generate the top level combined index.
Should be run from the gsdl-tutorial directory, not from the
subdirectory
java -cp
$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
-DGSDLHOME=$GSDLHOME ApplyXSLT
$processing_dir/xml-to-top-index.xsl $source_dir/tutorial_en.xml
> $output_dir/index.html
Windows versions of these commands are like the
following:
- Run setup in the top level
directory of your Greenstone installation
- Create a subdirectory in gsdl-tutorials
for your output files. If you are using multiple languages and want to
create top level index files, then you should name the directories en,
fr, es, and ru, otherwise the links won't be valid.
- cd to the appropriate directory
- Generate the index page:
java -cp
%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar
-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-index.xsl
%source_dir%\tutorial_en.xml > index.html
- Generate the individual pages
java -cp
%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar
-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-many-html.xsl
%source_dir%\tutorial_en.xml | perl -S
%GSDLHOME%\gli\help\splithelpdocument.pl
- Generate a single HTML file containing
all tutorials
java -cp
%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar
-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-one-html.xsl
%source_dir%\tutorial_en.xml > all_tutorials.html
- Generate the top level combined index.
Should be run from the gsdl-tutorial directory, not from the
subdirectory
java -cp
%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar
-DGSDLHOME=%GSDLHOME% ApplyXSLT
%processing_dir%\xml-to-top-index.xsl
%source_dir%\tutorial_en.xml > %output_dir%\index.html
The generate-html.sh/bat scripts are shell
scripts that carry out a lot of these commands for you.
The English version of the tutorial is currently
valid for Greenstone 2.71, while the French, Spanish and Russian
versions are valid for Greenstone version 2.70. If you want to generate
a workshop using one of these languages, you will need to use
Greenstone 2.70.
You will need to replace the appropriate source
file name for tutorial_en.xml in the above commands. Edit common.xsl,
and change 'en' to e.g. 'fr' in the line
<xsl:variable name="diction"
select="dict:new('en')"/>
If you want an up-to-date tutorial for another
language, one option is to have the tutorial text in English, with all
the button names and GLI references in the other language. To do this,
use tutorial_en.xml as the source file, but change the dictionary
language as above.
For a workshop, you can select a subset of the
exercises, and place them in any order you want. This is done with the
manifest file. A sample manifest file has been included - this is one
that we used for a Greenstone workshop in Hawaii, 2006.
Once you have created your manifest file, you
need to run the following. You can choose whether to have a separate
HTML file per session, or the entire workshop in one file.
- Run source setup.bash in the top
level directory of your Greenstone installation
- Create a subdirectory in gsdl-tutorials for
your output files, eg "workshop"
- cd to this directory
- Generate one file per workshop session:
java -cp
$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-workshop.xsl
$source_dir/tutorial_en.xml | perl -S
$GSDLHOME/gli/help/splithelpdocument.pl
- Generate a single file containing all sessions
java -cp
$shared_dir:$GSDLHOME/gli:$GSDLHOME/gli/classes:$GSDLHOME/perllib:$shared_dir/xalan.jar
-DGSDLHOME=$GSDLHOME ApplyXSLT $processing_dir/xml-to-one-workshop.xsl
$source_dir/tutorial_en.xml > workshop.html
Windows versions of these commands are like:
- Run setup in the top level directory
of your Greenstone installation
- Create a subdirectory in gsdl-tutorials for
your output files, eg "workshop"
- cd to this directory
- Generate one file per workshop session:
java -cp
"%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar"
-DGSDLHOME=%GSDLHOME% ApplyXSLT %processing_dir%\xml-to-workshop.xsl
%source_dir%\tutorial_en.xml | perl -S
"%GSDLHOME%\gli\help\splithelpdocument.pl"
- Generate a single file containing all sessions
java -cp
"%shared_dir%;%GSDLHOME%\gli;%GSDLHOME%\gli\classes;%GSDLHOME%\perllib;%shared_dir%\xalan.jar"
-DGSDLHOME=%GSDLHOME% ApplyXSLT
%processing_dir%\xml-to-one-workshop.xsl %source_dir%\tutorial_en.xml
> workshop.html
The generate-workshop.sh/bat scripts are shell
scripts that carry out these commands for you.
A basic manifest file looks something like this:
<Manifest>
<Title>Greenstone Hawaii Workshop, Jun 2006</Title>
<Section id="one" number="1">
<Heading>Lab 1: Installing Greenstone</Heading>
<TutorialRef id="install_greenstone"/>
<TutorialRef id="update_greenstone_installation"/>
</Section>
<Section id="two" number="2">
<Heading>Lab 2: Building a collection</Heading>
<TutorialRef id="small_html_collection"/>
<TutorialRef id="word_pdf_collection"/>
</Section>
</Manifest>
The manifest has a Title, which is the
Workshop title. Then it is divided into Sections. Each section
will be saved in a separate file, named using the Section's id
attribute. A Section has a Heading, and then a list of TutorialRefs
- these indicate which tutorials should go into the section. The id
attribute must match the Tutorial id used in tutorial_en.xml.
For more control over the exercises, you can specify
only part of a tutorial should be used in one exercise.
For example, in the Hawaii workshop, we split the Word and PDF exercise
over two lab sessions. To do this we used <SplitTutorialRef>.
<SplitTutorialRef id="word_pdf_collection" titleextra="—Part A" type="preceding" split="Heading[2]">
<EndNotes>
<Comment><Text>In exercise 2.1 we correct some of this incorrect metadata by manually adding Dublin Core Title metadata.</Text></Comment>
</EndNotes>
</SplitTutorialRef>
....
<SplitTutorialRef id="word_pdf_collection" titleextra="—Part B" type="following" current="true" split="Heading[2]">
<BeginNotes>
<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>
</BeginNotes>
</SplitTutorialRef>
SplitTutorialRef has some extra attributes:
titleextra: some extra text to be added to the Title, in this
case, we add "— Part A" and "— Part B".
split: the XML node to split the tutorial on.
type: whether we want the sections before the split (preceeding)
or after the split (following).
current: set to true if the node to split on should be included.
SplitTutorialRef can also include BeginNotes
and/or EndNotes element - this is for extra text of
instructions that should be added to the start or end of the exercise.
The format inside BeginNotes and EndNotes follows the format of the
general tutorial, see below.
tutorial_en.xml is the main file. Make
modifications in that. The translator takes care of the other languages.
All <Text> elements need a unique id, and all
need to be on their own lines, with no other tags (apart from tags
inside the text).
Tag examples:
<Link>url</Link> for URLS.
<Link url="url">display text</Link> for URLS which
have different text to display
<Format>format statement, or macro statement</Format>
<Path>file paths</Path>
<Menu> menu sequence, eg File → New</Menu>
Bullet lists:
<BulletList>
<Bullet>
<Text id="223">first bullet point</Text>
</Bullet>
...
</BulletList>
Main numbering
<NumberedItem>
text, comments etc go in here
</NumberedItem>
Block of text in italics:
<Comment>
<Text id="xxx">some italics text</Text>
</Comment>
Section heading:
<Heading>
<Text id="009">A heading</Text>
</Heading>
To print the tutorials with appropriate highlighting in
place, need to set "print background colours" in page setup (mozilla).