Greenstone3 for Greenstone2 Users

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.

• 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.

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.

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. Important Note: This option is for greenstone 3.02 only, it will be added into 3.03 later. For large collections, you can avoid rebuilding by running a conversion script instead. Important Note: for the version 3.03 you must use this conversion script not the one provided by the Greenstone3 installer. This script will be added into the next release.

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.

<pre>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</pre>

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

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

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

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)

<pre>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</pre>

You need to do this for each collection you wish to port. To see a list of available Greenstone2 collections, run this command: <pre>ls /opt/greenstone2/collect/</pre>

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

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.

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 http://en.wikipedia.org/wiki/XML 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.