Finish cleaning up this chapter.

Sponsored by: iXsystems

en_US.ISO8859-1/books/handbook/l10n/chapter.xml

@@ -27,9 +27,9 @@
 
     <para>&os; is a distributed project with users and contributors
       located all over the world.  As such, &os; supports localization
-      into many languages.  This allows a user to view, input, or
+      into many languages, allowing users to view, input, or
-      process data in non-English languages.  Currently, one can
+      process data in non-English languages.  One can
-      choose from most of the major languages, including but not
+      choose from most of the major languages, including, but not
       limited to:  Chinese, German, Japanese, Korean, French, Russian,
       and Vietnamese.</para>
 
@@ -41,30 +41,20 @@
 
     <para>The term internationalization has been shortened to
       <acronym>i18n</acronym>, which represents the number of letters
-      between the first and the last letters of internationalization.
+      between the first and the last letters of <literal>internationalization</literal>.
-      <acronym>L10n</acronym> uses the same naming scheme, coming from
+      <acronym>L10n</acronym> uses the same naming scheme, but from
-      <quote>localization</quote>.  Combined together,
+      <literal>localization</literal>.  The
       <acronym>i18n</acronym>/<acronym>L10n</acronym> methods,
       protocols, and applications allow users to use languages of
       their choice.</para>
 
-    <para><acronym>i18n</acronym> applications are programmed using
-      <acronym>i18n</acronym> kits under libraries.  These allow
-      developers to write a simple file and translate displayed menus
-      and texts to each language.</para>
-
     <para>This chapter discusses the internationalization and
-      localization features of &os;.  Since there are many aspects of
+      localization features of &os;.  After reading this chapter, you
-      the <acronym>i18n</acronym> implementation at both the system
+      will know:</para>
-      and application levels, more specific sources of documentation
-      are referred to, where applicable.</para>
-
-    <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
-	<para>How different languages and locales are encoded on
+	<para>How locale names are constructed.</para>
-	  modern operating systems.</para>
       </listitem>
 
       <listitem>
@@ -77,13 +67,17 @@
       </listitem>
 
       <listitem>
-	<para>How to use <application>Xorg</application> effectively
+	<para>How to configure <application>Xorg</application> for
-	  with different languages.</para>
+	  different languages.</para>
       </listitem>
 
       <listitem>
-	<para>Where to find more information about writing
+	<para>How to find <acronym>i18n</acronym>-compliant applications.</para>
-	  <acronym>i18n</acronym>-compliant applications.</para>
+      </listitem>
+
+      <listitem>
+	<para>Where to find more information for configuring specific
+	  languages.</para>
       </listitem>
     </itemizedlist>
 
@@ -146,22 +140,6 @@
 	</tgroup>
       </table>
 
-      <indexterm><primary>encodings</primary></indexterm>
-      <indexterm><primary>ASCII</primary></indexterm>
-
-      <para>Some languages, such as Chinese or Japanese, cannot be
-	represented using ASCII characters and require an extended
-	language encoding using either wide or multibyte characters.
-	Older applications may mistake these encodings for control
-	characters while newer applications usually recognize 8-bit
-	characters.  Depending on the implementation, users may be
-	required to compile an application with wide or multibyte
-	character support, or configure it correctly.  The rest of
-	this section describes the various methods for configuring the
-	locale on a &os; system.  The next section will discuss the
-	considerations for finding or compiling applications with i18n
-	support.</para>
-
       <para>A complete listing of available locales can be found by
 	typing:</para>
 
@@ -170,6 +148,34 @@
       <para>To determine the current locale setting:</para>
 
       <screen>&prompt.user; <userinput>locale</userinput></screen>
+      <indexterm><primary>encodings</primary></indexterm>
+      <indexterm><primary>ASCII</primary></indexterm>
+
+      <para>Language specific character sets, such as
+	  ISO8859-1, ISO8859-15, KOI8-R, and CP437, are
+	  described in &man.multibyte.3;.  The active list of character sets can be found at the <link
+	xlink:href="http://www.iana.org/assignments/character-sets">IANA
+	Registry</link>.</para>
+
+      <para>Some languages, such as Chinese or Japanese, cannot be
+	represented using <acronym>ASCII</acronym> characters and require an extended
+	language encoding using either wide or multibyte characters.
+	Examples of wide or multibyte encodings include EUC and Big5.
+	Older applications may mistake these encodings for control
+	characters while newer applications usually recognize these
+	characters.  Depending on the implementation, users may be
+	required to compile an application with wide or multibyte
+	character support, or to configure it correctly.</para>  
+
+    <note>
+      <para>&os; uses Xorg-compatible locale encodings.</para>
+    </note>
+
+    <para>The rest of
+	this section describes the various methods for configuring the
+	locale on a &os; system.  The next section will discuss the
+	considerations for finding and compiling applications with <acronym>i18n</acronym>
+	support.</para>
 
     <sect2 xml:id="setting-locale">
       <title>Setting Locale for Login Shell</title>
@@ -193,7 +199,7 @@
 	<listitem>
 	  <indexterm><primary>MIME</primary></indexterm>
 
-	  <para><envar>MM_CHARSET</envar> which sets the MIME
+	  <para><envar>MM_CHARSET</envar>, which sets the <acronym>MIME</acronym>
 	    character set used by applications</para>
 	</listitem>
       </itemizedlist>
@@ -218,7 +224,7 @@
 
 	<para>This first method is the recommended method as it
 	  assigns the required environment variables for locale name
-	  and MIME character sets for every possible shell.  This
+	  and <acronym>MIME</acronym> character sets for every possible shell.  This
 	  setup can either be performed by each user or it can be
 	  configured for all users by the superuser.</para>
 
@@ -257,7 +263,7 @@ me:\
 	<para>Alternately, the superuser can configure all users of
 	  the system for localization.  The following variables in
 	  <filename>/etc/login.conf</filename> are used to set the
-	  locale and MIME character sete:</para>
+	  locale and <acronym>MIME</acronym> character set:</para>
 
 	<programlisting><replaceable>language_name</replaceable>|<replaceable>Account Type Description</replaceable>:\
 	:charset=<replaceable>MIME_charset</replaceable>:\
@@ -336,7 +342,7 @@ me:\
 	<sect3 xml:id="startup-file">
 	  <title>Shell Startup File Method</title>
 
-	  <para>This method is not recommended as each shell that is
+	  <para>This second method is not recommended as each shell that is
 	    used requires manual configuration, where each shell has a
 	    different configuration file and differing syntax.  As an
 	    example, to set the German language for the
@@ -407,11 +413,11 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting>
 	area if the screen font uses a bit 8 column.</para>
 
       <para>To see the list of available keymaps, type
-	<filename>ls /usr/share/syscons/keymaps</filename>.  When
+	<command>ls /usr/share/syscons/keymaps</command>.  When
 	specifying the <replaceable>keymap_name</replaceable>, do not
-	include the <filename>.kbd</filename> suffix.  When uncertain
+	include the <filename>.kbd</filename> suffix.  To test
-	as to which keymap to use, &man.kbdmap.1; can be used to test
+	keymaps without rebooting,
-	keymaps without rebooting.</para>
+	use &man.kbdmap.1;.</para>
 
       <para>The <literal>keychange</literal> entry is usually needed
 	to program function keys to match the selected terminal type
@@ -507,13 +513,13 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting>
 	    </row>
 
 	    <row>
-	      <entry>Japanese</entry>
+	      <entry>Chinese/Japanese/Korean</entry>
-	      <entry><package>chinese/kon2</package></entry>
+	      <entry><package>chinese/zhcon</package></entry>
 	    </row>
 
 	    <row>
-	      <entry>Chinese/Japanese/Korean</entry>
+	      <entry>Japanese</entry>
-	      <entry><package>chinese/zhcon</package></entry>
+	      <entry><package>chinese/kon2</package></entry>
 	    </row>
 
 	    <row>
@@ -535,7 +541,7 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting>
 	&man.syscons.4; driver occupies the
 	<literal>0xd0</literal>-<literal>0xd3</literal> range in the
 	character set.  If the language uses this range, move the
-	cursor's range.  To enable this workaround for &os;, add the
+	cursor's range by adding the
 	following line to <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>mousechar_start=3</programlisting>
@@ -751,7 +757,7 @@ Comment out for now. If needed, can be added as note in new Printing chapter.
 	converted to &postscript; or PDF formats using language
 	specific converters.</para>
     </sect2>
-    -->
+Not sure where to put this section, perhaps as a note in the File system chapter?
     <sect2>
       <title>Kernel and File Systems</title>
 
@@ -773,62 +779,32 @@ Comment out for now. If needed, can be added as note in new Printing chapter.
 	character sets, and chosen &os; filesystem character sets.
 	Refer to &man.mount.msdosfs.8; for details.</para>
     </sect2>
+        -->
   </sect1>
 
   <sect1 xml:id="l10n-compiling">
-    <title>Compiling <acronym>i18n</acronym> Programs</title>
+    <title>Finding <acronym>i18n</acronym> Applications</title>
 
-    <para>The &os; <link xlink:href="&url.base;/ports/index.html">&os;
+    <para><acronym>i18n</acronym> applications are programmed using
-	Ports Collection</link> contains programs which provide
+      <acronym>i18n</acronym> kits under libraries.  These allow
-      application support for wide or multibyte characters for several
+      developers to write a simple file and translate displayed menus
-      languages.  Refer to the <acronym>i18n</acronym> documentation
+      and texts to each language.</para>
-      in the respective &os; port for more information on how to
+    <para>The <link xlink:href="&url.base;/ports/index.html">&os;
-      configure the application correctly or to determine which
+	Ports Collection</link> contains many
-      compile options to use when building the port.</para>
+      applications with built-in support for wide or multibyte characters for several
-
+      languages.  Such applications include <literal>i18n</literal> in their names for
-    <para>Some things to keep in mind are:</para>
-
-    <itemizedlist>
-      <listitem>
-	<para>Language specific single C chars character sets such as
-	  ISO8859-1, ISO8859-15, KOI8-R, and CP437.  These are
-	  described in &man.multibyte.3;.</para>
-      </listitem>
-
-      <listitem>
-	<para>Wide or multibyte encodings such as EUC and Big5.</para>
-      </listitem>
-    </itemizedlist>
-
-    <para>The active list of character sets can be found at the <link
-	xlink:href="http://www.iana.org/assignments/character-sets">IANA
-	Registry</link>.</para>
-
-    <note>
-      <para>&os; uses Xorg-compatible locale encodings instead.</para>
-    </note>
-
-    <para>In the &os; Ports Collection, <acronym>i18n</acronym>
-      applications include <literal>i18n</literal> in their names for
       easy identification.  However, they do not always support the
       language needed.</para>
 
-    <para>Many applications in the &os; Ports Collection have been
+    <para>Some applications can be compiled
-      ported with <acronym>i18n</acronym> support.  Some of these
+      with the specific
-      include <literal>-i18n</literal> in the port name.  These
-      and many other programs have built in support for
-      <acronym>i18n</acronym> and need no special
-      consideration.</para>
-
-    <indexterm>
-      <primary><application>MySQL</application></primary>
-    </indexterm>
-    <para>However, some applications such as
-      <application>MySQL</application> need to have their
-      <filename>Makefile</filename> configured with the specific
       charset.  This is usually done in the port's
       <filename>Makefile</filename> or by passing a value to
-      <application>configure</application> in the source.</para>
+      <application>configure</application>.  Refer to the <acronym>i18n</acronym> documentation
+      in the respective &os; port's source for more information on how to
+      determine the needed <application>configure</application> value 
+      or the port's <filename>Makefile</filename> to determine which
+      compile options to use when building the port.</para>
   </sect1>
 
   <sect1 xml:id="lang-setup">
@@ -853,8 +829,13 @@ Comment out for now. If needed, can be added as note in new Printing chapter.
 	<secondary>Russian</secondary>
       </indexterm>
 
+      <para>This section shows the specific settings needed to
+	localize a &os; system for the Russian language.  Refer to
+	<link linkend="using-localization">Using Localization</link> for
+	a more complete description of each type of setting.</para>
+
       <para>To set this locale for the login shell, add the following
-	lines into each user's
+	lines to each user's
 	<filename>~/.login_conf</filename>:</para>
 
       <programlisting>me:My Account:\
@@ -944,25 +925,23 @@ Option "XkbOptions"  "grp:toggle"</programlisting>
 
       <note>
 	<para>The Russian XKB keyboard may not work with
-	  non-localized applications.</para>
+	  non-localized applications.  Minimally localized applications should call a
-      </note>
-
-      <para>Minimally localized applications should call a
 	<function>XtSetLanguageProc (NULL, NULL, NULL);</function>
 	function early in the program.</para>
+      </note>
 
-      <para>See <link xlink:href="http://koi8.pp.ru/xwin.html">
+      <para>See <uri xlink:href="http://koi8.pp.ru/xwin.html">http://koi8.pp.ru/xwin.html</uri>
-	  KOI8-R for X Window</link> for more instructions on
+	for more instructions on
 	localizing <application>Xorg</application> applications.  For
 	more general information about KOI8-R encoding, refer to
-	<link xlink:href="http://koi8.pp.ru/">KOI8-R -
+	  <uri xlink:href="http://koi8.pp.ru/">http://koi8.pp.ru/</uri>.</para>
-	  Russian Net Character Set</link>.</para>
     </sect2>
 
     <sect2>
       <title>Additional Language-Specific Resources</title>
 
-      <para>Some intro text here...</para>
+      <para>This section lists some additional resources for
+	configuring other locales.</para>
 
       <indexterm>
 	<primary>localization</primary>
@@ -992,11 +971,7 @@ Option "XkbOptions"  "grp:toggle"</programlisting>
 	  <listitem>
 	    <para>The &os;-Taiwan Project has a Chinese HOWTO for &os;
 	      at <uri
-		xlink:href="http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/">http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/</uri>
+		xlink:href="http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/">http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/</uri>.</para>
-	      using many Chinese ports.  The current editor for the
-	      <literal>&os; Chinese HOWTO</literal> is Shen
-	      Chuan-Hsing
-	      <email>statue@freebsd.sinica.edu.tw</email>.</para>
 	  </listitem>
 	</varlistentry>
 
@@ -1005,9 +980,9 @@ Option "XkbOptions"  "grp:toggle"</programlisting>
 	    Languages</term>
 
 	  <listitem>
-	    <para>Slaven <email>eserte@cs.tu-berlin.de</email> wrote a
+	    <para>A
-	      tutorial on using umlauts on &os;.  The tutorial is
+	      tutorial on using umlauts on &os; is
-	      written in German and is available at <uri
+	      available in German at <uri
 		xlink:href="http://user.cs.tu-berlin.de/~eserte/FreeBSD/doc/umlaute/umlaute.html">http://user.cs.tu-berlin.de/~eserte/FreeBSD/doc/umlaute/umlaute.html</uri>.</para>
 	  </listitem>
 	</varlistentry>
@@ -1016,9 +991,8 @@ Option "XkbOptions"  "grp:toggle"</programlisting>
 	  <term>Greek Language Localization</term>
 
 	  <listitem>
-	    <para>Nikos Kokkalis <email>nickkokkalis@gmail.com</email>
+	    <para>A complete article on Greek support in &os;
-	      has written a complete article on Greek support in &os;.
+	      is available <link
-	      It is available <link
 		xlink:href="&url.doc.base;/el_GR.ISO8859-7/articles/greek-language-support/index.html">here</link>,
 	      in Greek only, as part of the official &os; Greek
 	      documentation.</para>
@@ -1043,7 +1017,7 @@ Option "XkbOptions"  "grp:toggle"</programlisting>
 	    <para>Some &os; contributors have translated parts of the
 	      &os; documentation to other languages.  They are
 	      available through links on the <link
-		xlink:href="&url.base;/index.html">main site</link> or
+		xlink:href="&url.base;/index.html">&os; web site</link> or
 	      in <filename>/usr/share/doc</filename>.</para>
 	  </listitem>
 	</varlistentry>