Issue 2090: document how to use LANG with Java sources

git-svn-id: http://scons.tigris.org/svn/scons/trunk@3307 fdb21ef1-2011-0410-befe-b5e4ea1792b1

diff --git a/src/engine/SCons/Tool/javac.xml b/src/engine/SCons/Tool/javac.xml
index ee9368534a3b4297bebb0a3401f1af36dc442470..e68263503fe8f6e7b7398353ad94ddaedb8aec8e 100644 (file)
--- a/src/engine/SCons/Tool/javac.xml
+++ b/src/engine/SCons/Tool/javac.xml
@@ -61,13 +61,28 @@ will generate a corresponding
 <filename>sub/dir/Foo.class</filename>
 class file.
 
-Example:
+Examples:
 
 <example>
 env.Java(target = 'classes', source = 'src')
 env.Java(target = 'classes', source = ['src1', 'src2'])
 env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
 </example>
+
+Java source files can use the native encoding for the underlying OS.
+Since SCons compiles in simple ASCII mode by default,
+the compiler will generate warnings about unmappable characters,
+which may lead to errors as the file is processed further.
+In this case, the user must specify the <literal>LANG</literal>
+environment variable to tell the compiler what encoding is uesd.
+For portibility, it's best if the encoding is hard-coded
+so that the compile will work if it is done on a system
+with a different encoding.
+
+<example>
+env = Environment()
+env['ENV']['LANG'] = 'en_GB.UTF-8'
+</example>
 </summary>
 </builder>