<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.7//EN" "/usr/GNUstep/System/Libraries/Resources/DTDs/gsdoc-0_6_6.dtd" >
<gsdoc base="LanguageSetup">
  <head>
    <title>Using Traditional Chinese and Other Languages</title>
    <author name="Yen-Ju Chen">
      <url url="http://www.gnustep.org/developers/whoiswho.html"/>
    </author>
    <version>$Revision$</version>
    <date>$Date$</date>
  </head>
  <body>
    <chapter>
      <heading>Using Traditional Chinese and Other Languages</heading>
      <p>This is an introduction to using Traditional Chinese and
  other languages in GNUstep. Note, however, that I have only tested
  these instructions with Traditional Chinese of either BIG5 or
  Unicode (iso10646-1) encoding. But since GNUstep is generally
  internationalized, this introduction could be applied to other
  languages with limited modification.</p>
  <section>
    <heading>Default Encoding</heading>
    <p>
    GNUstep uses Unicode internally. Everything it reads will be
    converted into Unicode. It will assume that everything it reads is in
    NSISOLatin1StringEncoding (iso8859-1) as the default encoding except
    scripts with escape (\u) ahead. User can change the default encoding
    by setting the environment variable <code>GNUSTEP_STRING_ENCODING</code>.
    </p>
    <p>For example, in bash:</p>
    <example>
      GNUSTEP_STRING_ENCODING = NSBIG5StringEncoding
      export GNUSTEP_STRING_ENCODING
    </example>
    <p>Now, it will assume that everything it reads without an escape is
    NSBIG5StringEncoding (BIG5). GNUstep will also write anything into
    this default encoding. </p>
    <p>There is a handy tool to convert between encodings:
    cvtenc. Programmers should use this tool to convert property
    lists to Unicode before releasing them.</p>
  </section>
  <section>
    <heading>Input</heading>
    <p>In XWindows, GNUstep use the XIM input method. Any XIM-server
  should be able to input script into GNUstep. The way GNUstep knows
  the encoding of the input is from the environment variable
  <code>LC_CTYPE</code>. In order to input Traditional Chinese,
  <code>LC_CTYPE</code> must be set for example, in .xinitrc</p>
    <example>
      LC_CTYPE=zh_TW.Big5
      export LC_CTYPE
    </example>
  <p>Right now, GNUstep supports UTF8 and Big5 encoding in input. If it
  doesn't work for your language, try to add more encoding support in
  <code>-initWithDelegate:display:name:</code>
  (back/Source/x11/XIMInputServer.m).</p>
  </section>
  <section>
    <heading>Display</heading>
    <p>Depending on the graphics library you use, GNUstep handles font
  display slightly differently. You can choose the graphics library
  when configuring the backend:</p>
  <example>
    ./configure --enable-server=x11 --enable-graphics=xlib
  </example>
  <p>the argument <code>--enable-graphics</code> could be either
  <code>xlib</code> or <code>art</code> for now. Personally I would
  suggest using art, which offer better font management.</p>
  <p>You can specify the font and size you want to use with
  the GNUstep defaults system. For exmample:
  </p>
  <example>
    defaults write NSGlobalDomain NSFont "Ar Pl Kaitim Big5"
    defaults write NSGlobalDomain NSFontSize 16
  </example>
  <p>The font name should be the same as the font name of `xlsfonts`
  output, but each word has to be capitalized. If you don't know
  what font names GNUstep supports, use the font panel in Ink.app
  to find out the font name.</p>
  </section>
  <section>
    <heading>Xlib</heading>
    <p>GNUstep will use a font cache in ~/GNUstep/Library/Font/Cache/
  to store the fonts of XWindows. Everytime you add more fonts to
  XWindows, you have to delete this cache and let the program build a
  new one. When you specify the default font, GNUstep will
  look it up in the font cache, and pick up the matched font in XWindows,
  then use this font to display text. GNUstep also support Xft for
  anti-aliased font display. Add GSFontAntiAlias=YES to your defaults
  to activate it. In order to use Traditional Chinese properly, always
  set it.  In order to use Xft, you also need to set freetype or
  xtt in your XF86Config (most of the time this is done for you.)</p>
    <p>Here is the problem you might meet when using Chinese fonts
  (arphic) in GNUstep:</p>
    <p>Each font will be assigned as big-0 or iso8859-1
  in fonts.dir by default, but actually arphic font is iso10646-1
  encoding. XWindows usually does the encoding conversion internally. So
  when you use "Ar Pl Kaitim Big5", you have a
  chance of picking up either big5-0 or iso8859-1 encoding, and neither
  works for GNUstep for unknown reason. The solution is:</p>
    <list>
      <item>Add iso10646-1 in fonts.dir, and it has to be in front of
    big5-0. Order is important to pick the right one.</item>
      <item>Set the default GSFontMask = *-iso* so that font cache
      won't pick up the big5-0 encoding.</item>
    </list> 
    <p>That's it. GNUstep should pick up the right font
  (iso10646-1). Since the mapping between NSFont in GNUstep (without
  encoding information) and font in XWindows (with encoding
  information) may not be unique ("Ar Pl Kaitim Big5" could be
  "-arphic-ar pl kaitim big5-*-*..-big5-0" or "-arphic-ar pl kaitim
  big5-*-*..-iso8859-1" or "-arphic-ar pl kaitim
  big5-*-*..-iso10646-1"), you have to put the iso10646-1 font in
  front of other encodings and use GSFontMask to filter out other
  possible choices so that GNUstep can pick up the correct one. And
  for now, I can only use the iso10646-1 font for Chinese
  display. Font with other encoding (including big5) does not work
  and is not well-tested.</p>
  <p>If you still have problems, look at the
  back/Source/xlib/XftFont.m and dump the font name of NSFont and
  encoding of the corresponding XWindows font. Sometimes the font
  cache can't find the matched XWindows font, and sometimes the
  encoding of the XWindows font is different from what Xft got. An
  example of the latter is that Xft will think the encoding of
  "-arphic-ar pl kaitim big5-*-*..-big5-0" is "apple-roman". Only
  "-arphic-ar pl kaitim big5-*-*..-iso10646-1" can be recognized as
  "iso10646-1" correctly. Therefore, make sure GNUstep picks the right
  XWindows font.</p>
  </section>

  <section>
    <heading>Art</heading>
    <p>The art backend use freetype for font management, and
  minimizes encoding problems. Simply add a Chinese font into your
  font collection as with other fonts, and enjoy the beautiful Chinese
  characters.</p>
  </section>

  <section>
    <heading>Summary</heading>
    <p>GNUstep supports internationalization and
  localization. In a few steps, you should be able to use it with your
  language.</p>
    <list>
      <item>Set <code>GNUSTEP_STRING_ENCODING</code> to read/write
    locally encoded files, including Localizable.strings.</item>
      <item>Set the correct <code>LC_CTYPE</code>. If your XIM-Server
    doesn't support UTF8 or Big5 encoding, try to add your encoding
    into XIMInputServer.m</item>
      <item>Assign the font using the GNUstep defaults tool, and use
      the art backend.</item>
    </list> 
  </section>

    </chapter>
  </body>
</gsdoc>


