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:

1. SYMPTOM: Visiting http://localhost:8383/greenstone3/library after running the Greenstone 3 server shows an empty page. If you try to investigate this issue on Windows, GS3's tomcat server output in the black DOS window can contain some strange characters or legitimate characters from other languages 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.

CAUSE: This occurs because the PC's encoding setting does not correctly interpret the bytes of data of the interfaceConfig.xml file being loaded in, due to encoding differences.

FIX: This issue has been fixed since Dec 2019, several 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:

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.
6. Windows requires further configuration changes followed by a restart. The most important is the 3rd one below:
   • Rightclick on your Windows Desktop, choose Display Settings. In the search box, search for "Language Settings". Then the Language configuration page opens, under Windows Display Language select the language setting appropriate for you.
   • Go to Control Panel > Clock and Region > Region.
     • In the Formats tab, under Format, select your language/country's language format setting.
     • In the Administrative tab, under the Language for non-unicode programs section, press the Change system locale button. Your preferred locale may already be selected, if not select it here.
     • Most importantly, still in the Adminstrative tab, on Windows 10, there is a tickbox option for Beta: Use Unicode UTF-8 for worldwide language support. Ensure you tick this. (Details of what this setting does when you switch it on are here.) While investigating the overall encoding issues described on this page in a Chinese locale, we found that this new setting available on Windows 10 more fully supports the encoding fixes listed above. Earlier versions of the Windows OS may not provide complete support because this new setting is absent.
   • Don't forget to restart your machine.

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

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.

• If you're working with a nightly Greenstone binary obtained from www.greenstone.org/caveat-emptor, the fixes will be available in your Greenstone installation and you just have to manually activate the fixes as follows:
  1. Use the Windows file explorer to go to perllib/cpan/Encode (which in a GS3 installation is located within its gs2build subfolder). Then rename the existing Locale.pm file to Locale.pm.old, then you'll finally be able to rename the Locale.pm.forLocaleIssue file to Locale.pm and rename Alias.pm.forLocaleIssue to Alias.pm.
  2. Use a text editor to open up perllib/plugins/DirectoryPlugin.pm (in a GS3 installation, this is located withing GS3's gs2build subfolder). Somewhere near the top of this file, find the line that says:

     #use Encode::Alias;

     
     and check out the # sign at the start of that line so that you get

     use Encode::Alias;

     
     Then save the file with this change.

• If you're working with Greenstone 2.87 or earlier or Greenstone 3.09 or earlier, then:
  1. Use the Windows file explorer to go to perllib/cpan/Encode (which in a GS3 installation is located within its gs2build subfolder). Then rename the existing Locale.pm file to Locale.pm.old. Next, download Locale.pm.forLocaleIssue and Alias.pm.forLocaleIssue into your perllib/cpan/Encode folder, and rename them to Locale.pm and Alias.pm, respectively.
  2. Use a text editor to open up perllib/plugins/DirectoryPlugin.pm (in a GS3 installation, this is located withing GS3's gs2build subfolder). Somewhere near the top of this file, find the line that says:

     no strict 'subs';

     
     and insert the following line after it:

     use Encode::Alias;

     
     Then save the file.