Greenstone Manual Information
Contents
Requirements
To use this package to re-generate the Greenstone tutorial HTML, or generate a workshop, you need to have the following:
- Greenstone version 2.71 installed
- A Java runtime system
Contents of this package
- README.html
- This file
- xml-source directory
- Contains all the XML source files and images.
Any changes to the Manuals should be made to the source files in this directory.
The xml-source directory contains:
- en, es, fr, ru subdirectories, which hold the source files for English,
Spanish, French and Russian respectively. Each subdirectory contains 4 XML files
and an images subdirectory. The 4 XML files correspond to the 4 Greenstone
manuals: Develop's manual, Installer's manual, User's manual, and From Paper to
Collection manual. The images directory contains all the images for every
manual.
Note: The en folder for English is the primary one. Any changes should
be made to this folder and let the translator take care of other languages.
- manual.dtd: the DTD with the XML files
- processing directory
- Contains all the XSL files and CSS files for
running XSL transform:
- xml-to-top-index.xsl XSL Transform file to generate a top index file
for all the manuals.
- xml-to-index.xsl XSL Transform file to generate an index file for
individual chapters of one manual.
- xml-to-one-html.xsl XSL transform file to generate a single HTML page
for each manual.
- xml-to-many-html.xsl XSL transform file to generate individual HTML
files for each manual, every chapter is a HTML file.
- common.xsl Common XSL templates for use with all transforms.
- xml-to-pdf.xsl XSL Transform file to generate a PDF file for every
manual.
- fo-common.xsl Common XSL templates for use with PDF transforms.
- crossref-inter.xsl, crossref.xsl, crossref-pdf.xsl XSL files for
getting the correct link address for links that refer to other chapters,
sections, footnotes or other manuals. crossref-inter.xsl is used for generating
multiple HTML files, crossref.xsl for generating a single HTML file, and
crossref-pdf.xsl for generating PDF file.
- manifest.xml list of the manuals, used for generate the top index.
- pdf-fonts directory holds all the font files for languages whose
fonts are not included in the base 14 fonts that FOP supports(see
here
for more).
- generate-html.sh
- Shell script that generates all the HTML files
- generate-pdf.sh
- Shell script that generates all the PDF files
- clean-all.sh
- Shell script that clean all the generated files
File structure
When generate HTML files and PDF files without using the shell scripts, you should:
- First create a build subdirectory here if there isn't one.
- For each language, create a subdirectory with the language code (eg. en, fr, es, ru) as the name of the directory, if there isn't one.
- cd to the appropriate direcotry, copy the images folder and the style.css file here
- Create a HTML and a PDF subdirectory for the generated HTML and PDF files.
If you use the shell scripts, they will create the subdirectories for you.
The file structure of the build directory is like this:
--manuals
--build
--language-code
--html
(all the generated html files go here)
--pdf
(all the generated pdf files go here)
--images
style.css
Including the GLI Help in User Guide
The "Librarian Interface user guide" section in the User's Guide manual is generated from the GLI Help, so when GLI Help was updated, this section needs to be regenerated to an XML file under xml-source/language directory. To regenerate the XML file,
- Go to the Greenstone installation directory and run
source setup.bash
- Go to the
gsdl-documentation/shared
directory, run
java ApplyXSLT ../manuals/processing/gen-gli-help-to-manual-chapter.xsl $GSDLHOME/gli/help/{lang}/help.xml > ../manuals/xml-source/{lang}/help-{lang}.xml
replace {lang}
with a specific language code, for example:
java ApplyXSLT ../manuals/processing/gen-gli-help-to-manual-chapter.xsl $GSDLHOME/gli/help/en/help.xml > ../manuals/xml-source/en/help-en.xml
In the XML source file of User's Guide, GLI Help is included by means of defining an ENTITY(chap_gli) in the DTD. For example:
<!DOCTYPE Manual [
<!ENTITY chap_gli SYSTEM "help-en.xml">
]>
Generating HTML files
- Run source setup.bash in the top level directory of your Greenstone installation
- Create a subdirectory named build, if there isn't one. cd to the build directory, create a subdirectory named with the language_code if there isn't one, for example, en for English language.
- cd to the language_code directory, create a html subdirectory
- copy the images folder and style.css file here
The generate-html.sh scripts are shell scripts that carry out a lot of these
commands for you, we recommend to use this script to generate the HTML pages.
Generataing PDF files
- Run source setup.bash in the top level directory of the Greenstone installation
- Unzip the fop.zip file under shared directory
- Generate the PDF file:
export CLASSPATH=$CLASSPATH:../shared/fop/build/fop.jar:../shared/fop/lib
./../shared/fop/fop.sh -c ../shared/fop/conf/userconfig.xml -q -xsl processing/xml-to-pdf.xsl -xml xml-source/language-code/manual-name_language-code.xml -pdf build/language-code/pdf/manual-name_language-code.pdf
The generate-pdf.sh scripts are shell scripts that carry out a lot of these
commands for you, we recommend you to use
The current status of the manuals
- Developer's manual
- Greesntone 2.50, translated in Mar. 2004
- User's manual
- Greenstone 2.70, translated in Mar. 2006
- Installer's manual
- Greenstone 2.50, translated in Mar. 2004
- From Paper to Collection
- Greenstone 2.50, translated in Mar. 2004
The XML Format
Develop_en.xml, User_en.xml, Install_en.xml and Paper_en.xml in the en directory are the main files. Make modifications in those. 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).
All <Chapter>, <Section>, <Subsection>, <Part>, <Table>, <Figure> elements need a unique id.
See the DTD file for more information.
Translate into other languages
To tranlate these manuals into other languages, use Greenstone Translator to do this, see here.
The "module-name" for the manuals are devmanual, installmanual, papermanual and usermanual.
For languages whose fonts are not included in the base 14 fonts that FOP
supports, eg. Russian, new font may be required to install before generating PDF
files in these languages. Install a new language to FOP have 3 steps:
- Find an appropriate font file (in .PFM or .TTF format) that contains the
necessary fonts, and run to
generate an XML file
- Register to FOP by adding a new entry in the userconfig.xml file
- In fo-common.xsl, add a new language-value pair for the
font
variable.
[Example]
For example, for the Russian language, the L_10646.TTF
(under
Windows) TrueType Font file contains the required Cyrillic font, then run
java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;lib\xercesImpl.jar;lib\xalan.jar
org.apache.fop.fonts.apps.TTFReader [options] L_10646.TTF Cyrillic.xml
to generate the font xml configure file Cyrillic.xml
.
Then go to the conf
directory under fop installation directory,
open userconfig.xml
file, in <fonts>
element, add
<font metrics-file="//research/lh92/gsdl-documentation/shared/fop/conf/Cyrillic.xml"
kerning="yes" embed-file="//research/lh92/gsdl-documentation/shared/fop/conf/L_10646.TTF">
<font-triplet name="Cyrillic" style="normal" weight="normal"/>
<font-triplet name="Cyrillic" style="normal" weight="bold"/>
<font-triplet name="Cyrillic" style="italic" weight="normal"/>
<font-triplet name="Cyrillic" style="italic" weight="bold"/>
</font>
Then run fop with -c userconfig.xml
option to use the new
configuration.
ToDo list
- Windows scripts
- Automatic texts
Texts like button names should be automatic generated, like in greenstone tutorials, but currently we didn't do this because the manuals are supposed to be rewritten soon, but this shall be done after the reversion.
- PDF fonts (done, but for new languages still needs to find an appropriate
font set)
The XML to PDF transform require for a correct font set for a
specific language.
- Images in PDF files
Images should not be too long, otherwise cannot
generate the PDF file.
- Navigation buttons (done)
Add navigation buttons in the html pages.