Greenstone Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
**Release Name:** 2.84

**Release Date:** 
  * Release Candidate 1: 17 December 2010
  * Release Candidate 2: 25 Feb 2011
  * Greenstone 2.84: 1 April 2011

**Released:** Windows, GNU/Linux, Mac OS/X and Source distributions of Greenstone v2.84

===== Installation Instructions =====

  * **Important Note**: 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.
==== 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. If you want to install Greenstone into C:\Program Files on Windows 7 or Windows Vista you will need to run the installer with administrator permissions (this can be achieved by right clicking on the installer and choosing "Run as administrator"). And if you wish use the Greenstone Administration pages (which will be needed if you want to create user accounts for a Remote Greenstone server), then now is a good time to set a sensible password for that.

  * The installer initially unpacks into a temporary directory (/tmp on linux). Set the TMPDIR environment variable to change this.
  * The windows version can be installed anywhere, including paths with spaces and brackets (these caused a problem in previous releases).
  * The Linux and Mac versions must be installed into a path with *no* spaces.

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 
<code>./gs2-server.sh</code>

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.(*)

By default, the web servers restrict access to Greenstone pages to the local machine. 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. <nowiki>(**)</nowiki>

**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, do one of the following:

  * Rename the server.exe executable found in your Greenstone installation folder. Then the Start menu shortcut will run the Apache web server instead of server.exe. If you are using GLI, GLI will then also start up Apache instead of server.exe. Alternatively you can start the web server by running gs2-server.bat (located in your Greenstone installation folder).
  * Run gs2-web-server.bat - this will start the Apache web server, but won't affect the Start menu shortcut, or GLI's behaviour.


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 
<code>./gli/gli.sh</code>

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 [[legacy:tutorials:2.83_tutorial_exercises |Greenstone 2.83 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.(*) <nowiki>(**)</nowiki>

(*) 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.

<nowiki>(**)</nowiki> 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 a machine different to the one that is running the Greenstone server. To be able to run the Client-GLI application, you will need Sun Java 1.5.0 or greater installed and you will need to have:
  * Java's <tt>bin</tt> 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 
<code>./gli/client-gli.sh</code>

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://<host>:<port>/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.

  * To get your Greenstone installation set up as a remote server so that other GLI clients can connect to it, please see the section [[2.84_Release_Notes#Working_with_Remote_Greenstone_and_the_GLI-Client | Working with Remote Greenstone and the GLI-Client]].

==== Source Components and Source Distributions ==== 

There are two ways to get **Greenstone 2.84'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 have 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 extract 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.84-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 need an appropriate compiler:
  * XCode for Macs, 
  * the GNU compiler for Linux 
  * Visual C++ (Visual Studio) and Microsoft/Windows Platform SDK for Windows machines. 


//If you have gnome-lib// (if not, see 2 paragraphs below), then 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):
<code>./configure --enable-apache-httpd
make
make install</code>
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.)

**Note:** If you don't have the correct gnome-lib, then the compilation will fail with error messages about WVware. In that case, visit http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk which contains archived versions of gnome-lib for various operating systems. Download the one for your operating system that contains **mimimal** in its label, and extract its contents into your Greenstone installation's **ext** folder (after deleting any gnome-lib folder already inside the **ext** folder). Use a command terminal to go into the extracted gnome-lib folder and run
<code>source devel.bash</code>
Then go back to the Greenstone installation directory and run the configure and compile commands (above) once more.


**To compile on Windows**,

 
1. Edit the start of the makegs2.bat file in your Greenstone installation directory to contain the path to your Visual Studio's vcvars32.bat file (or vsvars32.bat file for later versions), this file is typically located in a place like C:\Program Files\Microsoft Visual Studio 10.0\VC\bin.

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.

==== Setting the Preview Command in GLI==== 
If you've installed Greenstone and are running GLI (the Greenstone Librarian Interface application) for the first time, and have just finished builing your first collection with it, GLI may not know what to do when you press the Preview Button. If it complains or does nothing when you press the Preview Button, you will need to tell it how to launch your default browser (and tell it to open on the collection page) upon pressing Preview.

The following specifies the commands you are likely to need. Paste the applicable one into GLI's File > Preferences menu > Connection tab > Preview Command field.

  * On Windows: 
<code>cmd.exe /c start "" "%1"</code>
  * On Mac:
<code>open %1</code>
Put %1 in quotes if your Greenstone installation path contains spaces.
  * On Linux systems: 
<code>firefox %1</code>
If you work with another browser, then type the command you'd use to launch that from the terminal, suffixed with %1 once again. (Embed %1 in quotes if you've installed Greenstone in a path containing spaces.)
**NOTE:** If GLI's Preview Button does not succeed in launching the browser with the collection URL, consult [[troubleshooting#GLI's_Preview_Button_fails_to_launch_a_web_page| this page of the FAQ for a suggested solution]].

==== Uninstallation ==== 
If you're on Linux or Mac and wish to uninstall Greenstone, you will need to give execute permissions to the uninstall/Uninstall.sh file in your Greenstone installation before you can run it.  

===== Important Changes =====

  * Greenstone can now be installed into a path with spaces on Windows (but not on Linux/Mac).
  * Apache installation is now optional when running a binary installer.
  * Greenstone now compiles and installs on 64-bit machines.
  * If Greenstone has been installed into a directory that is write-protected (such as C:\Program Files\Greenstone), Windows Vista and Windows 7 will now ask for elevated permissions (through a User Account Control dialog) when programs such as GLI or GEMS are run, so that these programs are able to modify collections and files in this directory.
  * The batch script that started the server on Windows has been renamed from gs2-server.bat to gs2-web-server.bat and now explicitly runs the Apache web server. A new file called gs2-server.bat now decides (based on the existence of server.exe) which server to run.
  * Greenstone will run correctly with Perl 5.10, including on Ubuntu machines.
  * The uninstaller no longer deletes everything from the installation directory, just the files Greenstone has installed. This was a problem earlier if Greenstone had been installed directly into an existing folder, e.g. My Documents, without a Greenstone subfolder.

==== Collection Building ==== 

  * Updated version of sqlite
  * Underscores no longer escaped in metadata. You can use the dmsafe: modifier in format statements to escape them if they are causing trouble for the macro system. 
  * Printing can be disabled for realistic book display - set gs.allowPrinting metadata for the document to 'false' to disable print access. 
  * If you are including files in your collection whose filenames are in encodings alien to your file system (say your system is using Windows-1252, but your file//names// are UTF-8, perhaps because they were generated on a Linux machine), then you can:
    * Set the gs.filenameEncoding metadata for the filenames of your file(s) to specify the encoding they are actually in. This means that upon building the collection, the filenames will be displayed correctly in your web browser. (GLI will also try to display the names of these files correctly.)
    * Alternatively, set the filename encoding option on the Plugin(s) that will be processing the files.
    * If neither gs.filenameEncoding metadata nor Plugins' filename encoding options are set, Greenstone's building process will resort to assuming your the names of the files in your collection are encoded in the encoding of your filesystem locale.
    * For notes related to setting up your Linux machine so that GLI can display filenames alien to your Linux filesystem settings (once you have set the gs.filenameEncoding metadata for such files), see **[[2.84_Release_Notes#Notes on setting up your Linux system to work with filename encodings alien to your filesystem settings | Notes]]**.

  * The non-standard collect directory option: 
    * GLI now allows you to choose a different location for the collect folder that will contain your collections. 
    * You can additionally open collections that are in a different collect folder from the default Greenstone one used thus far (for example, you can have your collect folder on your pen drive). 
    * New collections can likewise be created in a different collect folder and optionally based on existing collections located in a different collect folder. 
    * You can also copy and move collections from one location to another using GLI. 
    * NOTE: The non-standard collect directory feature is not supported by either GLI client or GLI applet.
  * Remote GLI now also supports collectgroups.
  * Archives database fixed so that a collection can be moved between Greenstone installations on different operating systems, and can still be rebuilt without reimporting. Note that incremental import/build is not possible if the collection is moved, as full paths are stored in the databases. 
  * Incremental import can be achieved by modifying files in the import folder and running 'incremental-import.pl' or by using a manifest file. This specifies a list of filenames or document identifiers to Index/Reindex/Delete. For more information about manifest files and how to use them, see the Manifest documented example collection. **[link]**
  * Incremental import/build improvements.
  * Can now use years as partition names for sub-collection indexes.
  * GLI now adds the greenstone metadata set to new collections by default. Contains metadata elements used by various parts of the Greenstone runtime systems.
  * The database type can now be set in GLI (in Design->Browsing Classifiers). The options are gdbm (the default), jdbm (a Java version) and sqlite (a relational database). 
  * If sqlite is selected as the database type, then an experimental search interface is available for the collection. Add sqlform to the list of SearchTypes in the Format->Format Features panel. This can then be selected by the user from the preferences page.
  * The Remote Greenstone server is now set up to find ImageMagick correctly. So image collections can be built using client GLI.

==== Plugins and Document Conversion ==== 

  * HTML, PDF, Word plugins now have a new option -metadata_field_separator, allowing multi-valued metadata to be extracted.
  * Documents now have 'lastmodifieddate' added as metadata in yyyymmdd format
  * New MediainfoOGVPlugin for importing OGV movie files. Requires Mediainfo (mediainfo.sourceforge.net) to be installed to extract metadata. Thanks to Yvan Arnaud who implemented this and has made it available.
  * [[MetadataXMLPlugin]] can now take a process_exp so metadata files don't have to be named metadata.xml.
  * The Powerpoint and Excel converters now work on all version of windows. **xlhtml-0.4.9.0**
  * New OAIMetadataXMLPlugin.pm for extracting information from OAI servers where metadata.xml files specify what to download from the OAI server. Done for Koha integration, but may be useful for other OAI servers. Thanks to DL Consulting Ltd.
  * All plugins now have a store_original_file option. This is useful for e.g. Text and HTML plugins to store the source file as an associated file so that it can be referred to when serving over OAI. 
  * PagedImagePlugin now scans the item file for which images/text files it includes, and blocks those from processing by other plugins. Previously it blocked all images. This means that one can now have paged image documents and individual images in the same collection. 
  * Extracted metadata, including that with a namespace, is now going to be added as ex.metadata. For example, dc.Title extracted from a document will be stored as ex.dc.Title. This means that GLI will now be able to display all extracted metadata. 
  * wv upgraded to 1.2.4 (used for Word document processing). 
  * Output options for PowerPoint processing with the Open Office extension include: 
    * html_multi: Two html files per slide, one containing the image, the other the text. Greenstone will process each file as an individual document. Image/Text/First/Prev/Next/Last links connect all the slides together.
    * pagedimg: A single item file with one page (an image and html file) per slide. 
  * DSpacePlugin: instead of ignoring all dc.description metadata, only ignores dc.description.provenance as this is the only one used internally by DSpace. Patch thanks to Pongtawat Chippimolchai, KIDS-D Project, Asian Institute of Technology
  * srclink now generated dynamically at runtime from srclink_file metadata, so it won't appear in GLI.

=== Extensions ===
We are developing an extension mechanism for Greenstone. Two extensions are available for download: **Open Office and PDF Box**, to process more recent versions of MS office documents and PDF document respectively.

  * **The Open Office extension** provides a document conversion facility if Open Office is already installed on the system. In order to use the Open Office extension, 
    * You will need [[http://www.openoffice.org/|Open Office]] installed. Then create an environment variable called SOFFICE_HOME and set this to the full path of your OpenOffice installation folder. Setting this environment variable is especially necessary if your OpenOffice is installed in a location other than C:\Program Files\OpenOffice.org 3. In that case, also ensure that your PATH environment variable contains the path to the "program" folder located in your SOFFICE_HOME path (the OpenOffice installation folder).
    * Once you have Open Office set up, download the Greenstone extension for it [[http://trac.greenstone.org/browser/gs2-extensions/open-office/trunk|from here]] (available in tar.gz and zip formats) and unzip into Greenstone's **ext** folder. 
    * Before you can use this (or any other Greenstone extension), you will need to quit GLI and GS2-server if either are open and then you will need to relaunch GLI (or run Greenstone scripts) from a fresh command terminal, in order for the extension to become available in the Greenstone environment.
    * With OpenOffice and the extension installed and the Greenstone environment set up for this, Greenstone's Word, PowerPoint and Excel Plugins will have a new option, "-openoffice_conversion", allowing conversion with Open Office instead of the existing converter. Switching on this new option means that more recent Office formats like docx can be included in Greenstone collections and processed by Greenstone.

  * **The PDF Box extension** provides support for conversion of PDF documents to text. It supports the latest PDF versions (unlike Greenstone's standard pdftohtml program), so is useful for collections with new PDF documents. 
    * Download the extension [[http://trac.greenstone.org/browser/gs2-extensions/pdf-box/trunk|from here]] (it's available in tar.gz and zip formats) and unzip into Greenstone's **ext** folder. The PDF Box extension does not require additional software to be installed.
    * Before you can use the extension, you will need to quit GLI and GS2-server if either are open and then you will need to relaunch GLI (or run Greenstone scripts) from a fresh command terminal, in order for the extension to become available in the Greenstone environment.
    * With the PDFBox extension installed and the Greenstone environment set up for this, there will now be a new option to the PDFPlugin called "pdfbox_conversion". In GLI you can turn this on by going to the "Document Plugins" section of the Design panel to configure the PDFplugin then tick the "pdfbox_conversion" option (found under the **AutoLoadConverters** section). Click OK to set the Plugin configuration and go to the Create panel to rebuild the collection. This time, documents of more recent PDF versions will also be processed.

==== Classifiers==== 
  * Phind phrase browser fixed to work with non-Latin character sets. Support added for displaying phrases in right-to-left languages. 
  * Hierarchy classifier with hfile fixed so that it keeps the specified classification numbers even when remove_empty_classifications is selected.
  * List classifier removeprefix and removesuffix options now work again.
  * List classifier new option: reverse_sort_leaf_nodes

==== OAI Server ==== 

  * dc.Identifier will now have a URL. This will be the value of gs.OAIResourceURL (user defined link to the document) if it's defined. Otherwise, if srclink_file (greenstone defined source file stored in index/assoc) metadata is defined, a link to this document will be used. Otherwise, a link to the Greenstone version of the document will be used.
  * Identifiers now use the OAI Identifier Scheme.  oai:repos-id:collection:doc-id Can be be version 1.1 or 2.0 (repositoryIdVersion in etc/oai.cfg sets this). The repository ID can be a unique identifier (for version 1.1) or a pre-registered domain name (for version 2.0). The repository ID can be set in etc/oai.cfg using the repositoryId field.
  * dc.Date is no longer used as the date stamp. lastmodifieddate metadata will be used, unless there is a user defined gs.OAIDateStamp provided. 
  * oaiinfo elements in etc/oai.cfg are now output as part of a description element, using a new gsdl_oaiinfo schema.
  * The xsl file attached to OAI output (to enable pretty viewing in a browser) has been updated to display the description element, and qualified dublin core metadata.

==== Formatting ==== 

  * new "htmlsafe:", "xmlsafe:", and "truncate(X):" (truncate metadata value to X characters) format statement modifiers. Thanks to DL Consulting Ltd.

==== Other ==== 

  * Next and previous search results now working for searching across multiple collections
  * z3950server now supports uniMARC, thanks to Yvan Arnaud. Edit the default_marc_format_d2m_ and default_marc_format_yaz_ variables in runtime-src/src/z3950/z3950server.cpp to change the default format. 
  * Added a safety check provided by Andrew Brooks (University of Dundee) for ensuring that a database with the wrong byte order for the machine cannot be opened for writing.

===== Further Notes on Installation and Running =====
==== Apache HTTPD Notes ==== 

Greenstone binary releases come with the Apache HTTPD web server precompiled and installed by default into Greenstone/apache-httpd. 
  * To uninstall it, delete the Greenstone/apache-httpd folder. 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 your Greenstone, copy the appropriate bits out of Greenstone's Apache httpd.conf file into your existing Apache's httpd.conf file. Then disable (or uninstall) Greenstone's Apache as described above.
  * If you want to use an alternative webserver, then set it up appropriately, and disable the Greenstone Apache server.
  * If you had installed Apache Httpd previously for the sole purpose of serving Greenstone, then you may like to uninstall it and use the one installed by Greenstone.

==== Additional notes to compiling manually ==== 
**On Windows**, use a DOS prompt to go into your Greenstone installation folder. You will need Visual C++ (either from Visual Studio or the Express version) and you may also need the Windows/Microsoft Platform SDK installed. FIRST run the Platform SDK's SetEnv.Cmd (if you have it). 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)
<code>nmake /f win32.mak
nmake /f win32.mak LOCAL_LIBRARY=1</code>

  * If you only want to compile up the apache web server, type:
<code>nmake /f win32.mak APACHE_HTTPD=1</code>

  * If you wish to clean the files generated during compilation (both intermediate files and binaries), type:
<code>nmake /f win32.mak clean</code>

  * Note that if you wish to compile things up (or clean) for debugging, then in all the above commands you would append
<code>DEBUG=1</code>


**On Linux and Mac**, configuring and compiling generally takes the form:
<code>./configure
make
make install</code>

  * By default, Greenstone is compiled with accent folding turned on. To disable it, you would run the configure step as follows:
<code>./configure --disable-accentfold</code>
As stated in the installation instructions, to compile the included apache web server, the configure step needs to be:
<code>./configure --enable-apache-httpd</code>

  * You can get rid of the files generated by compilation by using a Terminal to go into your Greenstone installation folder and running:
<code>make clean</code>
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:
<code>make distclean</code>

==== 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, since 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:
<code>gs2-server.bat</code>
  * to run GLI, type:
<code>gli\gli.bat</code>

  * 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 further 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:
<code>cd <here you'd type the full path to your Greenstone installation folder></code>
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:
<code>cd C:\Greenstone
gs2-server.bat</code>

E.g. on Linux or Mac:
<code>cd /home/me/greenstone
./gs2-server.sh</code>

==== Using gsicontrol script ==== 

The gsicontrol.sh/bat script is used by gs2-server.sh/bat, and provides much functionality: you can use it to change port number, start and stop the Apache web server, etc. It accepts many parameters like:
<code>
 web-start 
 web-stop
 web-restart 
 
 configure-admin
 configure-web
 configure-apache 
 configure-cgi 
 
 set-port 
 
 test-gsdlhome 
 web-stop-tested
</code>
You can use it as in the following example 

  - In a command window, go to your Greenstone installation folder and run setup.bat (if on Windows) or 'source setup.bash' (for Linux/Mac)
  - Then run "gsicontrol.sh/bat set-port". It will ask for a port number. Use e.g. 8282 (just to avoid conflicts with standard ports).
  - Now run "gsicontrol.sh/bat web-start". It will run the 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.
  - To stop the webserver at any point, you'd run "gsicontrol.sh web-stop" from your command window.


==== Working with Remote Greenstone and the GLI-Client ==== 
These instructions are more Greenstone 2.84-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 the value for the GSDLHOME line contains quotes around it. E.g.
<code>gsdlhome "C:\Program Files\Greenstone2"</code>
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 from the Windows Start Menu, or by opening a DOS prompt and typing the path to your Greenstone 2 installation and then running the gs2-server script. E.g.
<code>cd C:\Program Files\Greenstone2
gs2-server.bat</code>

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://<YOUR-MACHINE-NAME:YOURPORT>/greenstone/cgi-bin/library.cgi%% 
where if port were the default 80 it won't be displayed, e.g.  %%http://<YOUR-MACHINE-NAME>/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://<YOUR-MACHINE-NAME:YOURPORT>/greenstone/cgi-bin/gliserver.pl?cmd=check-installation)%%

At the end of the browser page, it is imperative that it says something like:
<code>"Installation OK!"</code>
(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):
<code>cacls "C:\Program Files\Greenstone2\collect" /P Everyone:F</code>
(If, on Vista or Windows 7, you installed Greenstone in an Admin area, such as in Program Files, then you would need change the the security settings of the collect directory: Right-click > Properties, then set the folder to "Everyone".)


On Linux you would do:
<code>chmod a+rw /my/path/to/my/Greenstone2.84/collect</code>


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, which will be what you chose upon installing Greenstone.


8. Enter the username and password for the new user.
  * In the Groups field, type "personal-collections-editor".
  * Press the Submit button.


9. 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.
<code>cd C:\Program Files\Greenstone2\gli
client-gli.bat</code>


10. 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://<YOUR-MACHINE-NAME:YOURPORT>/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%%


11. It will next ask you for a username and password. Type the values you entered for the new user you created in step 8.


12. The client-GLI dialog should finally open, and it will look the same as the usual (local) GLI.


==== Notes on setting up your Linux system to work with filename encodings alien to your filesystem settings ==== 

UTF-8 is a common encoding used in filesystems and for data content.

If you are working on a UTF-8 system, then Java (and therefore GLI) will not give you access to files that do not have UTF-8 filenames. This means that in GLI, attempts to drag and drop files with names that are not UTF-8 will fail on such systems. 

GLI will allow one to drag and drop files if the filesystem encoding was set to something that preserved the byte values of filenames (instead of destructively replacing characters that are not valid for the filesystem encoding with an "invalid" character, as happens with UTF-8 systems). In practice, this means that a filesystem encoding such as "Native Latin 1" (also called ISO-8859-1), which is a subset of Unicode, will preserve the underlying byte values in filenames, allowing you to drag and drop all sorts of filenames in GLI. 

Drag And Drop in GLI will work by default on Windows since it is not a UTF-8 filesystem, but rather one that has a large overlap with Native Latin 1. 

However, some Linux systems are set to UTF-8 by default, while others do not even have other encodings installed so you can't switch over.

The solution to making GLI work with "alien filename encodings" on such Linux systems is to switch the encoding to Native Latin 1 (this is **regardless** of what encoding your filenames are in). Where this is not installed, you would require **Admin rights**' to install Native Latin 1, before switching to it. The following contains instructions on doing both. Note that switching between installed encodings does **not** require Admin rights. 


**INSTALLING AND APPLYING A NEW FILESYSTEM ENCODING ON A LINUX MACHINE:**

The instructions are derived from the thread of questions and answers [[http://mail.openjdk.java.net/pipermail/i18n-dev/2008-September/000048.html|openjdk]] and [[http://ubuntuforums.org/showthread.php?t=423039|this page at Ubuntu Forums]].

First find out whether you are already working with a Linux system set to Native Latin 1 (ISO-8859-1). Check by typing the following in an x-term:
<code>locale -k LC_CTYPE | grep charmap</code>
If the settings are indeed set to Native Latin 1, it should tell you that (en_US.)ISO-8859-1 is active.


A) INSTALLATION OF A NEW FILESYSTEM ENCODING (Native Latin 1/ISO-8859-1): 

Installation of Native Latin 1 (ISO-8859-1), which requires Admin rights, may not be required: check if this encoding is already installed on the machine first. You can check by running the following two commands in an x-term:
<code>export LC_ALL=en_US.ISO8859-1 
export LANG=en_US.ISO8859-1</code>

If it doesn't come back with any messages that look like failure (such as the encoding not being found), then it is installed and should now be active. Otherwise you need Admin permissions to install Native Latin 1 (ISO-8859-1) on your Linux system, as follows:

1. Open /var/lib/locales/supported.d/local as Root user and, at the bottom of the file, add the line:

<code>en_US.ISO-8859-1 ISO-8859-1</code>

2. Repeat the above step with the file /var/lib/locales/supported.d/en 

3. **Optional:** Only if you wish to make the Native Latin 1 encoding the system default would you need to open /etc/default/locale as Root and change LANG="en_US.UTF-8" to LANG="en_US". (Or possibly LANG="en_US.ISO-8859-1".)

4. Then in an x-term, run the following to install the new encoding: 

<code>sudo locale-gen --purge</code>

5. Restart the machine. 

The above 5 steps need to be carried out **once** for en_US.ISO-8859-1 (Native Latin 1) to be supported by the machine. You would still need to apply the new encoding.


B) APPLYING THE NEWLY INSTALLED ENCODING AS THE FILESYSTEM (AND DISPLAY) ENCODINGS: 

6. Having restarted the machine, to make the newly-installed encoding the active one, run the following commands in an x-term again. You do not need Admin rights for issuing the following two commands:

<code>export LC_ALL=en_US.ISO8859-1 

export LANG=en_US.ISO8859-1</code>

7. You can check if it all worked by running: 
<code>locale -k LC_CTYPE | grep charmap</code>
Or by running:
<code>locale</code>
It should tell you that (en_US.)ISO-8859-1 is active.

8. Now run GLI from the same x-term to allow it to work with the Native Latin 1 filesystem encoding settings.


===== Patches to 2.84 =====
1. **WINDOWS:** There is a bug that will crash the apache web server if a search is performed in a collection built with Lucene. This bug can be fixed as follows:
  *Stop your GS2.84 web-server if it's running.
  * In a text editor, open up the file "apache-httpd/windows/conf/httpd.conf.in" located in your Greenstone installation directory.
  * In the file, look for the line:<code>PassEnv "USERPROFILE" "ProgramFiles" LANG</code>and change it to:<code>PassEnv "USERPROFILE" "ProgramFiles" LANG "TEMP"</code>
  * Save the file and restart the GS2 server. Searching a Lucene collection should be working again.


There were several unicode issues related to the following in the Greenstone 2.84 release:
  * List classifier when dealing with unicode metadata in bookshelf titles
  * PagedImagePlugin, when processing XML item files containinig unicode 
  * when adding unicode metadata to documents, which got faultily processed by MetadataXMLPlugin. 

The above have now been fixed. You can bring your Greenstone 2.84 installation up to date with these improvements as follows:

a. Make backup copies of the following files in your Greenstone2.84 installation:
  * perllib/plugins/MetadataXMLPlugin.pm
  * perllib/plugins/PagedImagePlugin.pm 
  * perllib/classify/List.pm

b. Download replacements for the above files from the following URLs and save them in the same locations as mentioned above:
  * http://trac.greenstone.org/browser/main/trunk/greenstone2/perllib/plugins/MetadataXMLPlugin.pm?format=txt
  * http://trac.greenstone.org/browser/main/trunk/greenstone2/perllib/plugins/PagedImagePlugin.pm?format=txt
  * http://trac.greenstone.org/browser/main/trunk/greenstone2/perllib/classify/List.pm?format=txt


2. **WINDOWS:** Authentication fails when using the Local Library Server (server.exe).

Work around: As this bug does not appear to affect the Apache web server included with Greenstone 2.84, you could use that instead. To do so, you would just rename the file "server.exe" in the top level of your Greenstone installation to a different file extension like "server.not". Then, when you launch the Greenstone Server from the Windows Start menu shortcut, it will use the Greenstone Apache web server instead.

This bug has been fixed for the next release.


===== Updated Translations =====

Thanks to the following people for new and updated translations since 2.83: 

  * Yohannes Mulugeta for Amharic translations
  * Kamal Salih Mustafa Khalafala for Arabic translations
  * Tigran Zargaryan for Armenian translations
  * Dilara Begum for Bengali translations
  * Dwight Martin for Burmese translations
  * Eduardo del Valle Pérez for Catalan translations
  * Yan Han for Simplified Chinese translations
  * Lilly Ho for Traditional Chinese translations
  * Aminath Riyaz for Dhivehi translations
  * Gerhard Riesthuis for Dutch translations
  * Mohammad Hassanzadeh for Farsi translations
  * Julian Fox for Italian translations
  * Gaku Yamaguchi for Japanese translations
  * Dr. K. S. Raghavan for Kannada translations
  * Zhanat Kulenov for Kazak translations
  * Shubhada Nagarkar for Marathi translations
  * Shiva Ram Shrestha and Mohan Raj Pradhan for Nepali translations 
  * Antonio Rasga for Portugal Portuguese translations
  * Vladimir R. Risojevic for Serbian translations
  * Harsha Balasooriya and H.G.P. Sujani Chathurika for Sinhalese translations
  * Tomáš Fiala for Slovak translations
  * Diego Spano for Spanish translations
  * S.K. Lalitha from Sarada Ranganathan Endowment for Library Science, Bangalore, for Tamil translations 
  * Dr. Vijayalakshmi Balakumar and Prof. R.S.R. Varalakshmi for Telugu translations
  * Gezae Haile and Yohannes Mulugeta for Tigrinya translations
  * Cao Minh Kiem for Vietnamese translations

For RC1, changes up to and including SVN revision 23502 (approximately).


For RC2, changes up to and including SVN revision 23737 (for GLI, r23734 for GS2 and r23739 for the release-kits).


For the GS284 release, changes up to and including revision 23835. For GLI: revision 23763 for GS2 and r23836 for the releasekits.