svn commit: r43871 - head/en_US.ISO8859-1/books/handbook/l10n

Dru Lavigne dru at FreeBSD.org
Tue Feb 11 14:59:29 UTC 2014


Author: dru
Date: Tue Feb 11 14:59:28 2014
New Revision: 43871
URL: http://svnweb.freebsd.org/changeset/doc/43871

Log:
  Initial pass at improving the flow and readability of this section.
  Several more commits to follow.
  
  Sponsored by: iXsystems

Modified:
  head/en_US.ISO8859-1/books/handbook/l10n/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/l10n/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/l10n/chapter.xml	Tue Feb 11 12:50:19 2014	(r43870)
+++ head/en_US.ISO8859-1/books/handbook/l10n/chapter.xml	Tue Feb 11 14:59:28 2014	(r43871)
@@ -101,29 +101,27 @@
 
     <indexterm><primary>locale</primary></indexterm>
 
-    <para>Localization settings are based on three main terms:
-      Language Code, Country Code, and Encoding.  Locale names are
+    <para>Localization settings are based on three components:
+      the language code, country code, and encoding.  Locale names are
       constructed from these parts as follows:</para>
 
     <programlisting><replaceable>LanguageCode</replaceable>_<replaceable>CountryCode</replaceable>.<replaceable>Encoding</replaceable></programlisting>
 
-    <sect2>
-      <title>Language and Country Codes</title>
-
       <indexterm><primary>language codes</primary></indexterm>
       <indexterm><primary>country codes</primary></indexterm>
 
-      <para>In order to localize a &os; system to a specific language,
-	the user needs to determine the codes for the specific country
-	and language as the country code tells applications which
-	variation of the given language to use.  The following are
-	examples of language/country codes:</para>
+      <para>The <replaceable>LanguageCode</replaceable> and <replaceable>CountryCode</replaceable> are used
+	to determine the country
+	and the specific language
+	variation.  <xref linkend="locale-lang-country"/> provides some
+	examples of <replaceable>LanguageCode</replaceable>_<replaceable>CountryCode</replaceable>:</para>
 
-      <informaltable frame="none" pgwide="1">
+      <table xml:id="locale-lang-country" frame="none" pgwide="1">
+	<title>Common Language and Country Codes</title>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
-	      <entry>Language/Country Code</entry>
+	      <entry>LanguageCode_Country Code</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
@@ -131,86 +129,49 @@
 	  <tbody>
 	    <row>
 	      <entry>en_US</entry>
-	      <entry>English - United States</entry>
+	      <entry>English, United States</entry>
 	    </row>
 
 	    <row>
 	      <entry>ru_RU</entry>
-	      <entry>Russian for Russia</entry>
+	      <entry>Russian, Russia</entry>
 	    </row>
 
 	    <row>
 	      <entry>zh_TW</entry>
-	      <entry>Traditional Chinese for Taiwan</entry>
+	      <entry>Traditional Chinese, Taiwan</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
-      </informaltable>
-
-      <para>A complete listing of available locales can be found by
-	typing:</para>
-
-      <screen>&prompt.user; <userinput>locale -a</userinput></screen>
-    </sect2>
-
-    <sect2>
-      <title>Encodings</title>
+      </table>
 
       <indexterm><primary>encodings</primary></indexterm>
       <indexterm><primary>ASCII</primary></indexterm>
 
-      <para>Some languages use non-ASCII encodings that are 8-bit,
-	wide, or multibyte characters.  For more information on these
-	encodings, refer to &man.multibyte.3;.  Older applications do
-	not recognize these encodings and mistake them for control
-	characters.  Newer applications usually recognize 8-bit
+      <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.  To provide
-	application support for wide or multibyte characters, the
-	<link xlink:href="&url.base;/ports/index.html">&os; Ports
-	  Collection</link> contains programs for several languages.
-	Refer to the <acronym>i18n</acronym> documentation in the
-	respective &os; port.</para>
-
-      <para>Specifically, the user needs to look at the application
-	documentation to decide how to configure it correctly or to
-	determine which compile options to use when building the
-	port.</para>
-
-      <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>
+	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>
 
-	<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>
+	<para>A complete listing of available locales can be found by
+	typing:</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>
-    </sect2>
+      <screen>&prompt.user; <userinput>locale -a | more</userinput></screen>
+      
+      <para>To determine the current locale setting:</para>
+      
+      <screen>&prompt.user; <userinput>locale</userinput></screen>
 
     <sect2 xml:id="setting-locale">
-      <title>Setting Locale</title>
+      <title>Setting Locale for Login Shell</title>
 
       <para>Usually it is sufficient to export the value of the
 	locale name as <envar>LANG</envar> in the login shell.  This
@@ -246,9 +207,6 @@
 	specific application configuration, and the
 	<application>Xorg</application> configuration.</para>
 
-      <sect3>
-	<title>Setting Locale Methods</title>
-
 	<indexterm><primary>locale</primary></indexterm>
 	<indexterm><primary>login class</primary></indexterm>
 
@@ -260,25 +218,20 @@
 	  system's shell
 	  <link linkend="startup-file">startup file</link>.</para>
 
-	<sect4 xml:id="login-class">
+	<sect3 xml:id="login-class">
 	  <title>Login Classes Method</title>
 
-	  <para>This method allows environment variables needed for
-	    locale name and MIME character sets to be assigned once
-	    for every possible shell instead of adding specific shell
-	    assignments to each shell's startup file.
-	    <link linkend="usr-setup">User Level Setup</link> can be
-	    performed by each user while
-	    <link linkend="adm-setup">Administrator Level Setup</link>
-	    requires superuser privileges.</para>
-
-	  <sect5 xml:id="usr-setup">
-	    <title>User Level Setup</title>
-
-	    <para>This provides a minimal example of a
-	      <filename>.login_conf</filename> located in a user's
-	      home directory which has both variables set for the
-	      Latin-1 encoding:</para>
+	  <para>This method assigns the required environment variables for
+	    locale name and MIME character sets
+	    for every possible shell.
+	    This setup can be either be
+	    performed by each user or it can be performed for all users by the
+	    superuser.</para>
+
+	    <para>This minimal example sets both variables for the
+	      Latin-1 encoding.  These lines were added to the
+	      <filename>.login_conf</filename> in an individual user's
+	      home directory:</para>
 
 	    <programlisting>me:\
 	:charset=ISO-8859-1:\
@@ -291,7 +244,7 @@
 	      for Traditional Chinese in BIG-5 encoding.  More
 	      variables are set because some applications do not
 	      correctly respect locale variables for Chinese,
-	      Japanese, and Korean.</para>
+	      Japanese, and Korean:</para>
 
 	    <programlisting>#Users who do not wish to use monetary units or time formats
 #of Taiwan can manually change each variable
@@ -307,16 +260,11 @@ me:\
 	:charset=big5:\
 	:xmodifiers="@im=gcin": #Set gcin as the XIM Input Server</programlisting>
 
-	    <para>See <link linkend="adm-setup">Administrator Level
-		Setup</link> and &man.login.conf.5; for more
+	    <para>See &man.login.conf.5; for more
 	      details.</para>
-	  </sect5>
-
-	  <sect5 xml:id="adm-setup">
-	    <title>Administrator Level Setup</title>
 
-	    <para>Verify that the user's login class in
-	      <filename>/etc/login.conf</filename> sets the correct
+	    <para>Alternately, the superuser can configure all users of the system for localization.  The following variables in the user's login class in
+	      <filename>/etc/login.conf</filename> set the correct
 	      language:</para>
 
 	    <programlisting><replaceable>language_name</replaceable>|<replaceable>Account Type Description</replaceable>:\
@@ -332,13 +280,14 @@ me:\
 	:lang=de_DE.ISO8859-1:\
 	:tc=default:</programlisting>
 
-	    <para>Whenever this file is edited, execute the following
+	    <para>Whenever <filename>/etc/login.conf</filename> is edited, remember to execute the following
 	      command to update the capability database:</para>
 
 	    <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
 
-	    <bridgehead renderas="sect4">Changing Login Classes with
-	      &man.vipw.8;</bridgehead>
+ 	    <sect4>
+	    <title>Changing Login Classes with
+	      &man.vipw.8;</title>
 
 	    <indexterm>
 	      <primary><command>vipw</command></primary>
@@ -348,9 +297,11 @@ me:\
 	      language:</para>
 
 	    <programlisting>user:password:1111:11:<replaceable>language</replaceable>:0:0:User Name:/home/user:/bin/sh</programlisting>
+	  </sect4>
 
-	    <bridgehead renderas="sect4">Changing Login Classes with
-	      &man.adduser.8;</bridgehead>
+	  <sect4>
+	    <title>Changing Login Classes with
+	      &man.adduser.8;</title>
 
 	    <indexterm>
 	      <primary><command>adduser</command></primary>
@@ -386,9 +337,11 @@ me:\
 		<screen>&prompt.root; <userinput>adduser -class language</userinput></screen>
 	      </listitem>
 	    </itemizedlist>
+	  </sect4>
 
-	    <bridgehead renderas="sect4">Changing Login Classes with
-	      &man.pw.8;</bridgehead>
+	  <sect4>
+	    <title>Changing Login Classes with
+	      &man.pw.8;</title>
 	    <indexterm>
 	      <primary><command>pw</command></primary>
 	    </indexterm>
@@ -396,10 +349,10 @@ me:\
 	      it in this form:</para>
 
 	    <screen>&prompt.root; <userinput>pw useradd user_name -L language</userinput></screen>
-	  </sect5>
-	</sect4>
+	  </sect4>
+	</sect3>
 
-	<sect4 xml:id="startup-file">
+	<sect3 xml:id="startup-file">
 	  <title>Shell Startup File Method</title>
 
 	  <note>
@@ -439,7 +392,6 @@ me:\
 	  <programlisting><envar>LANG=de_DE.ISO8859-1; export LANG</envar></programlisting>
 
 	  <programlisting><envar>setenv LANG de_DE.ISO8859-1</envar></programlisting>
-	</sect4>
       </sect3>
     </sect2>
 
@@ -677,6 +629,46 @@ keychange="<replaceable>fkey_number sequ
   <sect1 xml:id="l10n-compiling">
     <title>Compiling <acronym>i18n</acronym> Programs</title>
 
+    <para>The &os;
+	<link xlink:href="&url.base;/ports/index.html">&os; Ports
+	Collection</link> contains programs which provide
+	application support for wide or multibyte characters for several languages.
+	Refer to the <acronym>i18n</acronym> documentation in the
+	respective &os; port
+	for more information on how to configure the application correctly or to
+	determine which compile options to use when building the
+	port.</para>
+
+      <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
       ported with <acronym>i18n</acronym> support.  Some of these
       include <literal>-i18n</literal> in the port name.  These


More information about the svn-doc-all mailing list