**Release Name:** 2.83
**Release Date:** 24 November 2009
**Released:** Windows, GNU/Linux, Mac OS/X and Source distributions of Greenstone v2.83
This is a release designed to be used with the new edition of "How to build a digital library".
===== Installation Instructions =====
==== Binary distribution ====
Upon downloading the installer, run the executable: On Windows and Mac you need to double-click it to launch the installation dialog, on Linux you first need to set the downloaded executable's permissions to executable before you can run it from the terminal. It may take some time for the Greenstone installation dialog to appear. Once the installation dialog displays, you generally need to keep pressing the Next button until it is finished. However, when it asks for the location to install Greenstone in, make sure to choose a location on your file system for which you have access privileges.
* On Windows, make sure that the directory path does NOT have brackets in it, eg C:\Program Files (x86)\Greenstone is not a good choice. Use eg C:\Greenstone instead.
* The installer initially unpacks into a temporary directory (/tmp on linux). Set TMPDIR environment variable to change this.
When the installation process is finished, you can run the Greenstone Server or the Greenstone Librarian Interface (GLI):
1. On Windows, the included Greenstone Server can be launched from the shortcut in the Start menu. On Mac and Linux, use a terminal (in Macs this is found under Applications > Utilities > Terminal) to go into the Greenstone installation directory and run
./gs2-server.sh
The small Greenstone Server Interface (GSI) dialog will display. Pressing its Enter Library button will open a browser onto your Greenstone Digital Library home page.(*)
**Note:** The Windows version of Greenstone includes two server applications: server.exe and an apache web server. (Linux and Mac versions of Greenstone include only the apache web server). By default, the server.exe application is launched when you use the Windows Start menu shortcut to launch the server. To use the apache web server included with the Windows version of Greenstone, you would first have to rename the server.exe executable found in your Greenstone installation folder. Then you can run the apache web server by double-clicking the gs2-server.bat file that's also located in your Greenstone installation folder (or you can use the MS-DOS prompt to run this batch file).
By default, your Greenstone pages served using the apache web server will not be viewable from other machines. To change this, go to File > Settings in the Greenstone Server Interface dialog, and tick "Allow external connections". Click OK to save the settings, then press the Restart Library button. (**)
2. The Greenstone Librarian Interface (GLI) can be run from the Windows Start menu. On Mac and Linux, use a terminal to go into the Greenstone installation directory and run
./gli/gli.sh
First, as in (1) above, the Greenstone Server Interface (GSI) dialog will appear. Eventually the Greenstone Librarian Interface (GLI) dialog will appear. Refer to the [[http://wiki.greenstone.org/wiki/index.php/Tutorial_exercises|Greenstone tutorials]] for examples of using the GLI to create collections of documents. Once you have finished creating a collection, you can preview it by pressing the Preview button from GLI's Create tab. It will open your Greenstone collection in the web browser.(*) (**)
(*) If the web page displays a "Forbidden" message instead, go back to the GSI dialog, and use its File > Settings menu to change the Address Resolution method to one of the other options there. Then press the Restart Library Button in the main GSI dialog and see whether the browser page it opens now is the Greenstone home page. Otherwise try another Address Resolution option from the GSI dialog's Settings menu and see whether the pages are visible now.
(**) If you have your own external web server that you wish to use, then in your Greenstone installation directory, rename the folder apache-httpd to something else. Alternatively, you can rename the file gs2-server.sh (if on Linux/Mac) or gs2-server.bat (if on Windows) to something else.
3. The Client-GLI is the version of the Greenstone Librarian Interface that can be run on different machine from the one that is running the Greenstone server. To be able to run the Client-GLI application, you will need Java 1.4.2 or greater installed and you will need to have:
* Java's bin folder on your PATH
* JAVA_HOME set to point to your Java installation folder
If you follow Java's installation instructions, they will direct you on how to add the Java installation's bin folder to your system's PATH environment variable and how to set the JAVA_HOME environment variable.
If on Windows, you can run client-GLI from its shortcut in the Start Menu. On Linux and Mac systems, you would use a terminal to go into your Greenstone installation folder and then run
./gli/client-gli.sh
When the client-GLI starts up, a small dialog appears asking you to enter the URL of the remote Greenstone server's gliserver.pl file. This URL generally has the form: %%http://:/greenstone/cgi-bin/gliserver.pl%%, where you have to fill in the host and port values for the remote Greenstone server. After clicking OK, the client-GLI application window will appear. Client-GLI looks and works just like the GLI, except that most of the document processing takes place on the remote machine where the Greenstone server is running.
==== Source Components and Source Distributions ====
There's two ways to get **Greenstone 2.83's source code** in a compressed format (zip or tar.gz file):
1. If you didn't install a Greenstone binary version, you would get the Greenstone Source Distribution which contains the (uncompiled) source code.
2. If you downloaded and installed the Greenstone binary version already, you would only need to top up your installation with the source code by getting the Source Component. You would then unzip this in your Greenstone directory: On Windows, right-clicking on the zip file and choosing to extract its contents to this location should be sufficient. To extract to the correct location on Linux and Mac systems, you would need to use a Terminal to run "tar -xvzf Greenstone-2.83-source-component.tar.gz" from your Greenstone installation directory. Then all the tar.gz file's contents will end up inside the appropriate folders.
**To compile** the Greenstone source code, you would need
* XCode for Macs,
* the GNU compiler for Linux and
* Visual C++ (Visual Studio) and Microsoft/Windows Platform SDK for Windows machines.
To configure and compile on Mac and Linux machines, open a Terminal and run the following three commands from the Greenstone installation directory (each of them will take some time, but you can skip the first if you downloaded the Source Component):
./configure --enable-apache-httpd
make
make install
If you do not wish to compile up the included apache web server, leave the --enable-apache-httpd out of step 1.
(See also the section "Additonal notes to compiling manually" below.)
To compile on Windows,
1. Edit the start of the makegs2.bat file in your Greenstone installation directory to contain
* the path to the setenv.cmd file of your Microsoft/Windows Platform SDK installation
* and the path to your Visual Studio's vcvars32.bat file (or vsvars32.bat file for later versions).
2. Then run the makegs2.bat file from the DOS prompt. Type Y to extract the necessary files. When it asks you what you want to compile, either type 3 to compile up the server.exe web server, or type 4 to compile up the apache web server included with Greenstone.
==== IMPORTANT NOTE on uninstalling Greenstone 2.83 ====
If you have Greenstone 2.83 installed, and it is installed into a pre-existing folder with no Greenstone subfolder (eg installed directly into My Documents), DO NOT run the uninstaller, as it will delete all the files in that folder. Please manually delete all the Greenstone folders and files.
===== Further Notes on Installation and Running =====
==== Apache Notes ====
Greenstone binary releases come with Apache precompiled and install it by default into Greenstone/apache-httpd.
* Currently there is no option not to install apache. To uninstall it, delete the Greenstone/apache-httpd folder and the gs2-server.sh/bat. To disable the use of it, rename the apache-httpd folder to something else (then you can rename it back if you change your mind later).
* If you have an existing Apache web server installed and you want to set it up to serve this Greenstone, copy the appropriate bits out of Greenstone's Apache httpd.conf file into the one for your existing apache. Then disable/uninstall Greenstone's Apache as above.
* If you want to use an alternative webserver, then set it up appropriately, and disable the Greenstone Apache.
* If you have Apache installed previously for the sole purpose of serving Greenstone, then you may like to uninstall it and use the one installed by Greenstone.
==== Notes for Snow Leopard ====
These notes were provided by Michael Silver via the mailing list. Copied here in case they help someone else.
Note that you need to replace in the directions below with the actual folder you install Greenstone into (e.g., /Users/alexanderkroh/Greenstone/
I'm going to assume (there's that word) that you are using a 64-bit version of Snow Leopard. Intel Macs can have either a 32-bit or 64-bit processor. The processor version can be determined by looking in the "About this Mac" box (in the Apple menu). If it says "Intel Core Solo" or "Intel Core Duo" it is 32-bit. Otherwise, it's 64-bit. (Complete details straight from Apple are available at %%http://support.apple.com/kb/HT3696%% ) If you have a 32-bit OS, there is an additional issue with ImageMagick, but you most likely have a 64-bit version.
If you're not experienced with compiling things, your best bet is to use the binary distribution available from www.greenstone.org. It doesn't sound like you're going to gain anything by compiling from source.
Greenstone uses Perl to do a lot of its magic. Unfortunately, Snow Leopard updated the version of Perl included in the distribution, and the default one (5.10) doesn't work with Greenstone Librarian Interface (GLI). You need to modify the setup.bash file to correct this.
* Determine the version of Perl 5.8 that is installed on your computer.
*Using Terminal or Finder, determine the complete name for /usr/bin/perl5.8.x. This will likely either by perl5.8.8 or perl5.8.9.
* Open the /setup.bash file.
* Add lines near the top that read as below. Note that 5.8.9 is used as an example, but the number should match the number used in the filename in Step 1a.
* Set the correct perl version for GSDL: **export VERSIONER_PERL_VERSION=5.8.9**
*Save the file.
When first installed, GSDL does not include any icons to run the programs - they must be run from the command line. I suggest you run both programs (the server and the GLI) from the terminal window to start with, since you'll be able to see any errors that may occur. The steps are:
* Open a Terminal window.
*Navigate to the application directory chosen during the install process: **cd **
* Run the setup script. Note that it requires the dot, space, dot, slash, filename structure: **. ./setup.bash**
* Run the GSDL Server process: **./gs2-server.sh**
* Go to the File menu and choose Settings. Select the "Allow external connections" option. Restart the server.
* Open a new Terminal window by pressing -N.
* Navigate to the application directory as in Step 2.
* Run the setup.bash file as in Step 3.
* Change to the gli directory: **cd gli**
* Run the GLI script: **./gli.sh**
After you've verified that the programs run, you'll probably want to create icons to start them since running the programs from the command line is cumbersome. You can create icons to run them by using the Apple Script Editor (AppleScript Editor or Script Editor depending on your OS version). Open the Script Editor.
* Type the following in the program: **do shell script "/gs2-server.sh"**
* Save the file as an application with a meaningful name, such as GSDL-Server. Remember where you save it.
* Change the line above to read: **do shell script "/gli/gli.sh"**
* Save the file as an application with a meaningful name, such as GSDL-GLI. Remember where you save it.
* Quit the Script Editor.
These files can be run from where they were saved, or dragged into the dock or onto the desktop.
==== Perl 5.8.9 for Linux ====
On some newer distributions of Linux (such as Ubuntu), Perl version 5.10.x or later is installed on the system. This can be incompatible with perl scripts run manually or which are run by the Greenstone Librarian Interface (GLI). Perl 5.8.9 is still compatible, and so a version for Linux has been put into a tar.gz and made available at %%http://www.greenstone.org/bin-linux-perl-5.8.9.tar.gz.%%
If you are running the Greenstone perl scripts (manually or via GLI) on Linux and it complains about perl-related errors, download this tar.gz file, put it into your Greenstone installation folder. Then open a terminal to go into that folder and run
tar -xvzf bin-linux-perl-5.8.9.tar.gz
The above will put perl 5.8.9 inside Greenstone's bin/linux folder.
Next, get the updated [[http://trac.greenstone.org/export/21805/main/trunk/greenstone2/setup.bash|setup.bash]] script and put it in your greenstone installation folder. It tells Greenstone where to first look for an installation of Perl (instead of defaulting to the system version).
To make sure your Greenstone installation subsequently uses this Perl and not the default one installed on your machine, you will first need to use your terminal to go into the Greenstone installation directory and run
source setup.bash
before running any perl scripts manually and before running GLI.
If you run scripts manually (from the command line), run them as:
perl -S
==== Additional notes to compiling manually ====
**On Windows**, use a DOS prompt to go into your Greenstone installation folder. You will need Visual C++ (of Visual Studio) and the Windows/Microsoft Platform SDK installed. FIRST run the Platform SDK's SetEnv.Cmd. THEN run Visual C++'s vcvars32.bat (or vsvars32.bat). Now you can compile manually:
* To compile up server.exe, run the following commands (each takes several minutes)
nmake /f win32.mak
nmake /f win32.mak LOCAL_LIBRARY=1
* If you only want to compile up the apache web server, type:
nmake /f win32.mak APACHE_HTTPD=1
* If you wish to clean the files generated during compilation (both intermediate files and binaries), type:
nmake /f win32.mak clean
**On Linux and Mac**, configuring and compiling generally takes the form:
./configure
make
make install
* By default, Greenstone is compiled with accent folding turned on. To disable it, you would run the configure step as follows:
./configure --disable-accentfold
As stated in the installation instructions, to compile the included apache web server, the configure step needs to be:
./configure --enable-apache-httpd
* You can get rid of the files generated by compilation by using a Terminal to go into your Greenstone installation folder and running:
make clean
To clean all the files generated during both compilation AND configuration (all config files, other intermediate files and binaries), you would run the following instead:
make distclean
==== Additional notes to running Greenstone on Windows ====
On Windows, running the Greenstone Librarian Interface (GLI) or the Greenstone Server Interface (GSI) manually from a DOS prompt could be useful in diagnosing anything that goes wrong as it keeps any messages that were displayed during program execution visible in the DOS window.
To run GLI or GSI from the DOS prompt, first go into your Greenstone installation directory and then
* to run the GSI, type:
gs2-server.bat
* to run GLI, type:
gli\gli.bat
* If you have trouble running gs2-server.bat (For example, getting the error "Could not find the main class: org.greenstone.server.Server2. Program will exit."), then you can run gsicontrol.bat instead. (See below)
==== Notes on using a Terminal or DOS prompt ====
On Macs, the Terminal is an application that can be found under Applications > Utilities > Terminal.
On Windows, you can start up a DOS prompt by going to Start > Run and then typing cmd.
To go to your Greenstone installation directory using your terminal, you would type:
cd
On Windows you would use backslashes (\) and on Linux and Mac, you would use forward slashes (/) in file paths.
On Linux and Mac, to run a shell script (Greenstone's shell scripts are files that end on *.sh or *.bash), you would precede the scriptname with a ./
On Windows, to run a batch script (files that end on *.bat), just type its name out in full.
E.g. on Windows:
cd C:\Greenstone
gs2-server.bat
E.g. on Linux or Mac:
cd /home/me/greenstone
./gs2-server.sh
==== Using gsicontrol script ====
The gsicontrol.sh/bat script is used by gs2-server.sh/bat, and provides much functionality: change port number, start and stop the Apache web server, etc. It accepts many parameters like:
web-start web-stop web-restart
configure-admin configure-web configure-apache configure-cgi
set-port test-gsdlhome web-stop-tested
You can use it as in the following example
* In a command window, go to Greenstone install folder and run setup.bat (windows) or 'source setup.bash' (Linux/Mac)
* Then run "gsicontrol.sh/bat set-port". It will ask for a port number. Use eg 8282 (just to avoid conflicting with standard ports).
* Now run "gsicontrol.sh/bat web-start". It will run Apache web server.
* In a browser, enter "http://localhost:8282". It should show the message "It works" indicating that Apache is running.
* Then type "http://localhost:8282/greenstone/cgi-bin/library.cgi". It should show the Greenstone home page.
==== Working with Remote Greenstone and the GLI-Client ====
These instructions are more Greenstone 2.83-specific than the [[http://wiki.greenstone.org/wiki/index.php/Remote_Greenstone|general instructions]] for setting up Greenstone 2 as a remote server.
The following are steps to follow if you're on **Windows**. On **Linux**, you can skip steps 1 and 2, otherwise things are similar. For instance, you'll want to launch *.bash or *.sh script equivalents to the batch files listed. Also, you'll want to use forward slashes (/) instead of the Windows' backward slash (\) when specifying file paths.
1. If the path to your Greenstone installation contains any spaces (i.e. if any of the containing folders wherein your Greenstone is ultimately located contain spaces in their names), please open cgi-bin/gsdlsite.cfg in a plain text editor and make sure that thevalue for GSDLHOME line contains quotes around it. E.g.
gsdlhome "C:\Program Files\Greenstone2"
Save any changes.
2. Rename server.exe in your Greenstone installation folder to something else, say "_server.exe".
This is because you will need to use the included Apache web server for the remote Greenstone. By renaming the default library server in Greenstone 2, Greenstone will next look for the apache web server.
3. Now run the Apache web server included with your Greenstone, by opening a DOS prompt and typing the path to your Greenstone 2 installation and then running the gs2-server script. E.g.
cd C:\Program Files\Greenstone2
gs2-server.bat
Alternatively, you could use Windows Explorer to locate the gs2-server.bat file in your Greenstone2 installation folder and double click that file.
4. A dialog (the Greenstone Server Interface) will display. Press its central Enter Library button.
It will open a browser and take you to a page like: %%http://localhost/greenstone/cgi-bin/library.cgi%%
(OR: %%http:///greenstone/cgi-bin/library.cgi%%
where if port were the default 80 it won't be displayed, e.g. %%http:///greenstone/cgi-bin/library.cgi)%%
5. Replace the "library.cgi" part of the URL in the browser to "gliserver.pl?cmd=check-installation":
E.g. %%http://localhost/greenstone/cgi-bin/gliserver.pl?cmd=check-installation%%
(OR: %%http:///greenstone/cgi-bin/gliserver.pl?cmd=check-installation)%%
At the end of the browser page, it is imperative that it says something like:
"Installation OK!"
(If not check the error messages.)
6. Once again, open a DOS prompt. Type the following, but make sure to type the path to *your* Greenstone2 installation (the example below uses C:\Program Files\Greenstone2\collect):
cacls "C:\Program Files\Greenstone2\collect" /P Everyone:F
On Linux you would do:
chmod a+rx /my/path/to/my/Greenstone2.83/collect
7. Use the browser to go to your Greenstone home web page again.
* Now click on the Administration Page link and add a new user:
* Click the Add a New User link to the left
* You'll be requested for the admin username (type "admin") and password
8. Enter the username and password for the new user.
* In the Groups field, type "personal-collections-editor".
* Press the Submit button.
9. If you're on a linux machine that required you to install the [[http://wiki.greenstone.org/wiki/index.php?title=2.83_Release_Notes#Perl_5.8.9_for_Linux|Perl|5.8.9 bundle]], then you would need to do the following additionally:
* Grab [[http://trac.greenstone.org/export/21805/main/trunk/greenstone2/cgi-bin/gsdlCGI.pm|the|updated gsdlCGI.pm file]] and put it into your Greenstone2/cgi-bin folder, after moving the existing one out of the way.
* Use a text editor to open up your Greenstone2/cgi-bin/gsdlsite.cfg file, look for the property "perlpath", uncomment it by removing the "#" sign upfront and set it to the **bin** folder of [[http://wiki.greenstone.org/wiki/index.php?title=2.83_Release_Notes#Perl_5.8.9_for_Linux|your|custom Greenstone's Perl installation]]:
perlpath /my/linux/path/to/Greenstone2/bin/linux/perl/bin
10. Open a new DOS prompt. Either in this or another machine (assuming you want the Greenstone server on one machine and the client on another), go to the gli folder of your Greenstone 2 installation, and run client-gli.bat. E.g.
cd C:\Program Files\Greenstone2\gli
client-gli.bat
11. A dialog will eventually appear asking you for the URL of the Remote Greenstone server's gliserver.pl file.
* If your client-gli is running from a different machine to where your Greenstone server is running, you need to specify the name of that remote machine hosting the Greenstone server: %%http:///greenstone/cgi-bin/gliserver.pl%%
* If the client-gli is running on the same machine, you can generally type "localhost": %%http://localhost/greenstone/cgi-bin/gliserver.pl%%
12. It will next ask you for a username and password. Type the values you entered for the new user you creatred in step 8.
13. The client-GLI dialog should finally open, and it will look the same as the usual (local) GLI.
===== Important Changes =====
2.83 incorporates a few changes and bug fixes since 2.82, including:
* ex.metadata is now valid in collection configuration files. Previously, GLI could handle ex. metadata, but would strip off the ex before writing the config file. Now, ex is valid in the config file too.
* On MAC (and Linux), the expat library file is now being compiled up from the local Apache installation and is now included with Greenstone. The DYLD_LIBRARY_PATH and LD_LIBRARY_PATH include the path to the generated expat library file. This fixes an earlier bug where the path to the expat lib was pointing to the wrong location. It also had other side effects in that any expat library file found could have a version incompatible with the one required by Greenstone.
* Fixes to resumption token support in the OAI server (thanks to DL Consulting)
* new macro _collectionspecificscript_. Can be used in a collection's extra.dm file to add custom javascript to all pages. Use instead of _pagescriptextra_ if you want to add javascript to what is already there, rather than overwriting it.
* incremental build: will now recognise a newly added metadata.xml file, and will reimport all other files in the same directory. Many other minor bug fixes.
* sorting the build using -sortmeta option to import.pl fixed (wasn't working in 2.82). The -reversesort option has been moved from import.pl to ArchivesInfPlugin, as sorting happens when this plugin reads in the archiveinf-doc.gdb file.
* new macro _queryterms_, which is a space separated list of search terms. Like _cgiargq_ but without term and field modifiers. eg if _cgiargq_ was "[snail]:TX & [smith]:AU", then _queryterms_ would be "snail smith". Use in format statements for searching in PDFs instead of using _cgiargq_, eg:
The windows release was compiled on Windows Vista. It appears that some functionality is broken
when running on Windows XP, for example, the depositor, and particular commands for oaiserver.
Here are
[[http://wiki.greenstone.org/wiki/gsdoc/patches/2.83-windows-library.cgi|2.83-windows-library.cgi]]
and [[http://wiki.greenstone.org/wiki/gsdoc/patches/2.83-windows-oaiserver.cgi|2.83-windows-oaiserver.cgi]]
to download which have been compiled on Windows XP.
They should be copied into Greenstone's cgi-bin folder,
and renamed to library.cgi or oaiserver.cgi, respectively.
[[http://wiki.greenstone.org/wiki/gsdoc/patches/2.83-windows-server.exe|2.83-windows-server.exe]]
should be copied into the top Greenstone folder, and renamed to server.exe.
** Word document processing on Mac OS**
On the Mac, when processing Word documents, you may encounter an error (in Expert mode) like
Error executing wv converter:
dyld: Library not loaded: /usr/local/lib/libpng.3.dylib
If so, please download [[http://wiki.greenstone.org/wiki/gsdoc/patches/2.83-libpng.3.dylib|2.83-libpng.3.dylib]] and
save to **Greenstone/bin/darwin/imagemagick/lib/libpng.3.dylib**.
===== Updated Translations =====
Thanks to the following people for updated translations since 2.82:
* Prof. A. Neelameghan of the Sarada Ranganathan Endowment for Library Science, Bangalore for Kannada and Tamil translations
* Prof. Adalgisa Pinheiro for Brazilian Portuguese translations
* Claudia Wanderley for Brazilian Portuguese translations
* K.N. Prasad of the Sarada Ranganathan Endowment for Library Science, Bangalore for Kannada and Tamil translations
* K.S. Raghavan of the Sarada Ranganathan Endowment for Library Science, Bangalore for Kannada and Tamil translations
* Lavji N. Zala for Gujarati translations
* S.K. Lalitha of the Sarada Ranganathan Endowment for Library Science, Bangalore for Kannada and Tamil translations
* Shubhada Nagarkar for Marathi translations
* Prof. Vara Lakshmi for Telugu translations
* Dr. Wmen for Tamil translations
A special thanks to Veronica Liesaputra, a most dedicated Greenstone friend,
who has done more than her own work of developing the excellent Realistic Book tool
(and plugin to Greenstone). She has lugged round her Mac laptop well beyond the call
of duty to help debug and test this release of Greenstone, and spent hours of her time
with us over many days, so that 2.83 may work on Mac Tigers as well.