Greenstone3 for Greenstone2 Users

Greenstone3 for Greenstone2 Users

From GreenstoneWiki

Introduction

Greenstone3 is a complete redesign and reimplementation of the original Greenstone digital library software (Greenstone2). It retains all the advantages of Greenstone2 - for example, it is multiplatform, highly configurable, and soon-to-be multilingual software. It incorporates all the features of Greenstone2, and is backwards compatible: that is, it can build and run existing collections without modification. Written in Java, it is structured as a network of independent modules that communicate using XML: thus it runs in a distributed fashion and can be spread across different servers as necessary. This modular design increases the flexibility and extensibility of Greenstone.

Q & A

  • Where are my collections? - In Greenstone3, collections are stored in the web/sites/<sitename>/collect folder of your Greenstone3 installation. <sitename> can refer to any site in your Greenstone3 installation, the default site being localsite. If you accept all the defaults in a Windows install, your collections will be in C:\\Program Files\\Greenstone3\\web\\sites\\localsite\\collect.
  • How can I get my Greenstone2 collections into Greenstone3? - Basically you just copy them across then rebuild (easiest) or run a conversion script (fastest). See Porting Greenstone2 collections to Greenstone3.
  • What can go wrong? - Some problems remain in Greenstone3. See the Known Problems list for details. If you have other problems, you should join the Greenstone3 mailing list and ask your questions there.
  • Building new collections - is it different to Greenstone2? - No. You still use the same GLI, and create and build collections in the same way. The only differences are internal software differences.
  • Can I make a Greenstone CD-ROM that contains my collections? - No. There is no export to CD/DVD-ROM functionality in Greenstone3.
  • What are the advantages of moving to Greenstone3? - See Advantages for a list.
  • What are the disadvantages of moving to Greenstone3? - See Known Problems for a list.
  • Is there anything Greenstone2 can do that Greenstone3 can't? - Very little, except for exporting to CD-ROM and authentication. (One other example is that the collage image browser is not yet supported.)
  • What about the tutorial exercises? - They work just the same way as they did with Greenstone2; see the Tutorial Exercises for details.

Installation

Installing Greenstone3 is just as easy as installing Greenstone2. Simply run the appropriate installer for your system and follow the on-screen instructions. Greenstone3 is distributed as an InstallShield installer program, allowing it to be installed easily and in a familiar way. Installation guides for Windows and Linux are available.

Windows

To install Greenstone3, locate the file greenstone-3.XX-win32.exe and run it by double-clicking. After a delay, you will be asked to choose a language for the installation. Choose a language, then follow the on-screen instructions and click 'Finish'. Details about the installation instructions are below:

  • Install Directory

    This is the directory (folder) to install Greenstone to. The default option, C:\\Program Files\\Greenstone3, is usually appropriate.

  • Tomcat Port and Tomcat Shutdown Port

    Greenstone3 runs the Apache Tomcat Web Server in the background, to make your Greenstone library available in a web browser. This option specifies the port number which Tomcat runs on. The default for this option is 8080, and this is suitable for most users. However, if you have another web server or other server already running on port 8080, you will have to choose another, free port. Tomcat also opens a shutdown port, for receiving shutdown signals. Once again, the default port number 8005 is a good choice here, unless you are running another server on that port.

  • Setup Type

    You are able to customise which parts of Greenstone3 are installed. The 'Standard' installation is recommended for most users. A 'Source Code' option has also been provided, for people who wish to compile Greenstone themselves. And a 'Custom' option has been provided to enable users to select which features of Greenstone3 are installed.

Greenstone3 is now installed, and a new start menu group called Greenstone3 Digital Library Software v3.02 has been set up. There are four items in the start menu group, explained below.

  • Greenstone3 Digital Library

    This is the Greenstone3 Server - the main attraction of Greenstone! Run this to browse and search your collections.

  • Greenstone Editor for Metadata Sets

    This is a link to the GEMS program. Use this to edit metadata sets or create new ones.

  • Greenstone Librarian Interface

    This is a link to the GLI program. Use this to create and build your Greenstone collections.

  • Documentation

    This is a submenu which contains three documents - manuals for Greentone2 and Greenstone3, and a README File.

Linux

These instructions are for versions of desktop Linux with windowing support. If you meet these requirements but are unable to install, please let us know. To install Greenstone3, using the command line, locate and run the file greenstone-3.XX-linux.bin. Running these commands will achieve that: 

cd ~/Desktop/                         #change directory to wherever the setup file is
./greenstone-3.XX-linux.bin

After a delay, a window appears with instructions for installation. Follow these instructions and click 'Finish'. Details about each option are below:

  • Install Directory

    This is the directory (folder) to install Greenstone to. The default is /opt/greenstone3/, which is a good choice if you have write permission to the /opt/ directory. Be sure to remember the path where you installed Greenstone3, as this is needed for running the Greenstone server and GLI.

  • Tomcat Port and Tomcat Shutdown Port

    Greenstone3 runs the Apache Tomcat Web Server in the background, to make your Greenstone library available in a web browser. This option specifies the port number which Tomcat runs on. The default for this option is 8080, and this is suitable for most users. However, if you have another web server or other server already running on port 8080, you will have to choose another, free port. Tomcat also opens a shutdown port, for receiving shutdown signals. Once again, the default port number 8005 is a good choice here, unless you are running another server on that port.

  • Setup Type

    You are able to customise which parts of Greenstone3 are installed. The 'Standard' installation is recommended for most users. A 'Source Code' option has also been provided, for people who wish to compile Greenstone themselves. And a 'Custom' option has been provided to enable users to select which features of Greenstone3 are installed.

Greenstone3 is now installed and you can proceed to run the Greenstone3 server and the GLI.

  • To run the Greenstone3 server

    First change to the directory where you installed Greenstone, then run the gs3-server.sh script. To do that, execute the following commands: 

cd /opt/greenstone3/    (or wherever you installed greenstone3)
./gs3-server.sh
  • To run the GLI

    Run the gli4gs3.sh script. To do that, execute these commands: (from the path where you installed Greenstone3)

cd gli/
./gli4gs3.sh
  • To run GEMS

    Run the gems4gs3.sh script. To do that, execute these commands: (from the path where you installed Greenstone3)

cd gli/
./gems4gs3.sh

Server Options

After you have installed Greenstone3 and started the Greenstone server, you can change a number of server options. Most users will probably not need to do this. For those who do, the options can be viewed and changed by clicking File → Settings... in the Greenstone server window.

  • Tomcat Port

    This option selects the port number for running tomcat. For more information and for help choosing a Tomcat Port, see Tomcat Port and Tomcat Shutdown Port in the Installation section.

  • Enter the library automatically

    Check this option if you want your Greenstone library to be opened automatically in your selected browser each time you start up the Greenstone3 server.

  • Servlet

    This option specifies how your Greenstone library will be viewed. The library option views the Greenstone library with the new Greenstone3 look-and-feel. The classic-library option views the library with the 'classic' Greenstone2 look-and-feel. The tester option should only be used to test the installation of Greenstone and the Tomcat web server, to ensure that servlets can be run properly. And the gateway option views collections hosted on a SOAP web service. This option is helpful for developers who want to see an example of collections being accessed via the SOAP protocol. For more information, see section 6.1 of the Greenstone3 manual located at docs/manual/manual.pdf of your Greenstone3 installation directory.

  • Enter library using

    This option chooses what happens when you click the 'Enter Library' button in the Greenstone3 server window. You can choose to have the library launched in the default web browser for you computer system, or another browser located on your computer. If you choose the latter option, click browse and open the web browser executable file (e.g., for Mozilla Firefox, open the 'firefox'(Linux) or 'firefox.exe'(windows) binary file.

Moving Greenstone2 collections to Greenstone3

If you are a Greenstone2 user, you can move your collections from Greenstone2 to Greenstone3. Simply copy the appropriate folders from the Greenstone2 collect folder to the Greenstone3 collect folder, and then rebuild the collections in the GLI. For large collections, you can avoid rebuilding by running a conversion script instead.

Windows

These instructions assume Greenstone2 is installed to C:\\Program Files\\Greenstone2 and that Greenstone3 is installed to C:\\Program Files\\Greenstone3, so please make the necessary adjustments if you installed either version of Greenstone to a different folder.

To port a collection called mycoll, you would use a file browser to copy the folder C:\\Program Files\\Greenstone2\\collect\\mycoll to the folder C:\\Program Files\\Greenstone3\\web\\sites\\localsite\\collect. Then, open the collection in the GLI and rebuild it.

If the collection is very large, you may prefer to just run the convert_coll_from_gs2.pl conversion script, to avoid a lengthy rebuild. To do this, open up an MS-DOS box (Start → (All) Programs → Accessories → Command Prompt) and execute these commands. 

cd "C:\\Program Files\\Greenstone2"
setup
[Alternatively, 
cd "C:\\Program Files\\Greenstone3\\gs2build"
setup
]
cd "C:\\Program Files\\Greenstone3"
gs3-setup
gs2build\\bin\\windows\\perl\\bin\\perl.exe bin\\script\\convert_coll_from_gs2.pl \\
     -collectdir "C:\\Program Files\\Greenstone3\\web\\sites\\localsite\\collect" mycoll

If you need you collections to appear with the classic Greenstone2 look-and-feel, see the 'Servlet' section of Server Options

Linux

These instructions assume Greenstone2 is installed to /opt/greenstone2/ and that Greenstone3 is installed to /opt/greenstone3/, so please make the necessary adjustments if you installed either version of Greenstone to a different folder.

To port a collection called mycoll, you would copy the folder /opt/greenstone2/collect/mycoll/ to the folder /opt/greenstone3/web/sites/localsite/collect/. 

cd /opt/greenstone2/
cp -r collect/mycoll/ /opt/greenstone3/web/sites/localsite/collect/

Then, you would open the collection using the GLI and rebuild it. Or if you collection is very large and a rebuild would take too long, run the conversion script convert_coll_from_gs2.pl instead. On the command line, execute these commands: (from the Greenstone2 installation directory) 

cd /opt/greenstone2/
source setup.bash
[alternatively
cd /opt/greenstone3/gs2build
source setup.bash
]
cd /opt/greenstone3/
source gs3-setup.sh
bin/script/convert_coll_from_gs2.pl -collectdir /opt/greenstone3/web/sites/localsite/collect mycoll

You need to do this for each collection you wish to port. To see a list of available Greenstone2 collections, run this command: 

ls /opt/greenstone2/collect/

You may need to close and re-open the Greenstone3 server before the ported collections are available in Greenstone3.

If you need you collections to appear with the classic Greenstone2 look-and-feel, see the 'Servlet' section of Server Options

Advantages

There are a number of advantages to using Greenstone3 instead of Greenstone2. These include:

  • Distributed Computing Support

    It is easy for different Greenstone3 installations to communicate with each other and serve each others collections. SOAP connections allow the library to run in a distributed fashion.

  • Web Service

    Greenstone3 allows collections to be served in XML format over SOAP, which makes the information in Greenstone collections not only human-readable but also machine-readable.

  • Interface Customisation

    Greenstone3 replaces macros with XML and XSLT for customising the visual appearance of your collections. This affords users more power over the look-and-feel of collections. The library program generates page data in XML, which is converted to HTML using XSLT. All formatting is done using XSLT, so it makes it easier to customize than Greenstone2 in which some of the HTML is output by the library, and some by the macro files. It is very easy to get back the data in XML, if you want to use it for other purposes.

  • Development

    Greenstone3 is being actively developed, with new features being added and stability increasing all the time.

  • Berry Baskets

    Berry Baskets offer a way to gather documents of interest (juicy berries) while browsing Greenstone collections. When you turn the facility on from the Preferences page, a basket appears in your browser window. Now, whenever you see a document that interests you, you can drag-and-drop it into the basket - just like picking a berry! Later, you can review the basket's contents, and cut-and-paste them into an email. (Note, the "Send email to a friend" button does not work yet. Also, it works best under Firefox, rather than Internet Explorer)

  • Cross Collection Search

    Cross collection searching in Greenstone3 is provided across all collections by default. The requirement that collections must have the same indexes is no longer there as the default index is used for each one. However, this means that you can't select which indexes to search, and search result ranking may not be valid as different indexers rank results differently.

  • Multiple sets of collections and multiple interfaces

    A single Greenstone3 installation can have multiple sets of collections and multiple interface definitions. Greenstone2, on the other hand, has a single collect directory, and a single set of macros. Greenstone3 has multiple "sites" each of which has its own collect directory, and multiple "interfaces" each of which has its own set of XSLT files. Any site can be served using any interface.

  • Addition of New Features

    The library runtime is written in Java and is modular, making it a lot easier to add new features should they be needed.

Documented Example Collections

The documented example collections work in Greenstone3 with the following exceptions:

  • Some of the 'How this collection works' text is not relevant to the Greenstone3 context, and some of the links in this text don't work properly.
  • The style, formatting and authentication collections are not relevant:
    • Formatting and authentication demo
    • Garish version of demo collection
    • Cascading style sheets demo collection
  • Cross collection search is handled globally not at a collection level, so the Bibliography supplement collection is not relevant.

Tutorial Exercises

Most of the tutorial exercises work exactly the same with Greenstone3. Some have steps that only work in Greenstone2; these are listed below:

  • Scanned image collection, and
  • Advanced scanned image collection

    The Niupepa collection on which these exercises are based uses nested if s in its format statements. Nested if statements are not supported, so lists in these exercises do not display correctly.

  • Customization: macro files and stylesheets

    Macros are no longer used in Greenstone3, so much of this tutorial does not apply.

  • Formatting the Word and PDF collection

    The step entitled Opening PDF files with query terms highlighted causes the collection to break and become unavailable in your library. This is a case of a collection disappearing after a change to format statements. Skip this step, or undo it if you have already done it.

  • Building a multimedia collection
    • The step Using non-standard macro files does not apply because Greenstone3 does not use macros, so should be skipped.
    • The step Using different icons for different media types contains a format statement with a nested if statement.
    • The step Adding an image collage browser does not apply as Greentsone3 does not yet have a collage browser.

Known Problems

As Greenstone3 is still in its early stages of development, a number of problems and bugs remain. If your Greenstone2 collections do not work under Greenstone3, or if you are experiencing some unexpected behavior from Greenstone3, please read this list before contacting us.

  • Conversion of collect.cfg

    Greenstone3 still uses Greenstone2-style collect.cfg files internally, and converts these to Greenstone3-style XML files called colletionConfig.xml. Unfortunately, the conversion is not always perfect, and may cause some unexpected errors with your collection. As development continues, the conversions will get better. Eventually, Greenstone3 will work solely with collectionConfig.xml files, eliminating the need for this problematic conversion process.

  • Collections sometimes disappear after changes to format statements

    After changing a format statement in a collection, the collection may become unavailable. This is because the conversion of the collect.cfg file after the new format statement is introduced produces a collectionConfig.xml file containing malformed XML. A collection cannot be hosted in Greenstone3 without a valid collectionConfig.xml file, so the collection disappears from the library. The solution is to undo the edits which caused the problem.

  • Need to click preview after changes to format statements

    Unlike in Greenstone2, format statements are not applied automatically to their collections. To apply changes to format statements, you must click the 'Preview' button in the GLI to invoke an internal conversion script which applies the changes.

  • Nested ifs and ors

    At this stage, Greenstone3 can only handle if and or statements in its format strings which don't contain other if and or statements. If you try to nest if or or statements, some of the control characters (like the curly brace '{') will be interpreted as literal characters and will appear on the pages of your collection.

  • Refresh Error in the GLI

    After building a new collection in GLI, it may not appear in your Greenstone library. If this happens, check that your Greenstone Web Path is set correctly (File → Preferences... → Greenstone Web Path). For the default installation, this should be set to http://localhost:8080/greenstone3

  • Export to CD/DVD-ROM

    Exporting collections to CD-ROM and DVD-ROM is not supported in Greenstone3.