Table of Contents

Supporting running Greenstone in other locales on Windows 10

Greenstone testing work tends to be done in an English locale, with English specific settings. However, Greenstone is meant to support language users around the world, whose PCs and laptops may be set to different locales and other language settings.

Months after Greenstone 3.09 was released, we discovered that on a machine running Windows 10 which was set to the Chinese locale and other related settings, different aspects of Greenstone 3 did not function out of the box.

In particular, the following issues were detected, with their causes and fixes (which work on Windows 10) described below:

SYMPTOM: Previewing http://localhost:8383/greenstone3/library after running GLI or the Greenstone 3 server still shows an empty page. If you try to investigate this issue on Windows, GS3's tomcat server output in the black DOS window can mention an XML parsing error to do with </displayItem>. This comes from some strange characters or legitimate characters from other languages being randomly interspersed within a display language when interfaceConfig.xml is being parsed for loading in. The tomcat and greenstone logs, located in GS3/packages/tomcat/logs/catalina[…].out and GS3/web/logs/greenstone.log respectively, may contain similar output with multiple character sets wrongly interspersed.

This issue has been fixed since Dec 2019 and April 2020, months after Greenstone 3.09's release, and will be available from Greenstone 3.10 onwards when released. If you wish to implement this fix for yourself in Greenstone 3.09 or earlier or in any version of Greenstone 2, then read on.

COMPULSORY FIX PART 1

ADDITIONAL SYMPTOM: If you were to now open a DOS prompt and try to run gs3-setup.bat inside your Greenstone 3 (or setup.bat inside your Greenstone2), there are foreign or strange characters that appear in the DOS output window, before gs3-setup.bat (or setup.bat) ends with an error message and fails to set up the Greenstone environment.

CAUSE: This occurs because the Windows PC code page needs to a particular code page in order for the characters in setup.bat and gs3-setup.bat (which itself also calls setup.bat) to be interpreted correctly.

FIX:

  1. Open up your Greenstone 3's gs2build/setup.bat file (or, for Greenstone 2, open up the top-level setup.bat file) in a text editor. On Windows use regular Notepad, not Notepad++ as the latter can end up changing the encoding in the file from ASCII to something else, in which case new encoding problems will be introduced.
  2. Use the text editor to locate the section below near the top of the file:
    @echo off

setlocal enabledelayedexpansion

pushd "%CD%"
CD /D "%~dp0"
set GSDLLANG=en
  3. Then insert the following code after the above section:
    :: This script's contents were created in Windows codepage 850 (Western European).
:: When this script is run in non-English locales like the Chinese locale, the 
:: character content/encoding of this script can get wrongly interpreted by the
:: different encoding of the locale. And then the GS environment gets set wrongly
:: or incompletely in those cases.
:: So we force this script to be run and interpreted in codepage 850.
:: However, the Russian display strings in this script were desgined to work in the
:: default Russian Windows codepage 866. Whereas, codepage 850 works for this
:: script's remaining English, French, Spanish display strings. So:
if ("!GSDLLANG!" == "ru") (
	chcp 866
) else (
	chcp 850
)
  4. Save and close the file.
  5. If not launching Greenstone applications from the Windows Start Menu, then when you next run any part of the Greenstone suite hereafter to test the fix, make sure to use a fresh DOS prompt so that the updated greenstone environment will be used when you run setup.bat in greenstone 2, or gs3-setup.bat in Greenstone 3 which internally runs its gs2build\setup.bat.

PART 2 OF FIX: TRY THESE 2 SOLUTIONS

ONGOING SYMPTOM: If you now run GLI, visiting http://localhost:8383/greenstone3/library still shows an empty page. And the output in the black DOS window can still mention an XML parsing error to do with </displayItem> and possible foreign or strange characters (which upon investigation will reveal that interfaceConfig.xml couldn't be parsed properly because the locale setting isn't as required).

CAUSE: Still an locale issue leading to encoding problems.

FIX: Try Solution 1 below first, and if that doesn't work, (optionally undo it and then) try Solution 2.

SOLUTION 1

If you're using Greenstone 3:

SOLUTION 2

If the above didn't work, try the following to get previewing to work again.

For this, Windows will require system configuration changes followed by a restart.

We noticed the following symptom only once in the 3 test cases so far. It has not occurred in the remaining 2 test cases, so although we document its solution here, you may not need to carry out the instructions for this solution until you actual notice the problem (the symptom) described here.

SYMPTOM: Unable to successfully and completely run certain perl scripts successfully such as perl -S pluginfo.pl -describeall, despite setting up the Greenstone environment by running gs3-setup.
As a result, GLI may fail to launch properly.

You can test if this is the case by opening a new DOS prompt, using it to navigate into your Greenstone 3 installation area and then running the following 2 commands in sequence there:\\ 

gs3-setup.bat
perl -S pluginfo.pl -describeall

If you see error messages, proceed with the fix for this described below.

CAUSE:This is because the perl Locale.pm module in 3.09 and earlier releases was insufficient in its character encoding support.

FIX: Fixes for this have been committed for the future Greenstone 3.10 release and onwards, but at present they have not been made active yet.