[svnbook commit] r1336 - in trunk/src/en: . book
cmpilato
svnbook-dev at red-bean.com
Wed May 25 02:13:38 CDT 2005
Author: cmpilato
Date: Wed May 25 02:13:37 2005
New Revision: 1336
Modified:
trunk/src/en/TODO
trunk/src/en/book/ch07.xml
Log:
* src/en/book/ch07.xml
(Localization): Make edits based on my review of Ben's section addition.
* src/en/TODO
Add a 1.2 TODO item related to string recoding errors.
Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO (original)
+++ trunk/src/en/TODO Wed May 25 02:13:37 2005
@@ -13,6 +13,16 @@
* ch05: comparison of bdb and fsfs: make it clear that fsfs is now
the default, need --fs-type bdb to get bdb. [MIKE]
+ * ch07: character set conversion errors sidebar: 'Can't recode
+ string' has been changed to more descriptive errors that list the
+ source and target charsets:
+ svn: Can't convert string from native encoding to 'UTF-8':
+ [...]
+ svn: Can't convert string from 'UTF-8' to native encoding:
+ [...]
+ svn: Can't convert string from '%s' to '%s':"
+ [...]
+
* ch06: client-cred-caching: mention win32 encryption in
mod_authz_svn: groups can contain other groups [BEN]
Modified: trunk/src/en/book/ch07.xml
==============================================================================
--- trunk/src/en/book/ch07.xml (original)
+++ trunk/src/en/book/ch07.xml Wed May 25 02:13:37 2005
@@ -2487,21 +2487,23 @@
formats numbers or dates in a way specific to your part of the
world, or prints messages (or accepts input) in your native
language, the program is said to
- be <firstterm>localized</firstterm>.</para>
+ be <firstterm>localized</firstterm>. This section describes
+ steps Subversion has made towards localization.</para>
<sect2 id="svn-ch7-sect-5.1">
<title>Understanding locales</title>
- <para>Most modern operating systems have a notion
- of <quote>current locale</quote>—that is, the current
- region or country that the computer is located in. The value
- of the locale affects the way in which programs present data
- to the user, as well as the way in which they accept user
- input.</para>
-
- <para>On Unix-like systems, the value of the current locale can
- be seen by running the <command>locale</command>
- command:</para>
+ <para>Most modern operating systems have a notion of the
+ <quote>current locale</quote>—that is, the region or
+ country whose localization conventions are honored. These
+ conventions—typically chosen by some runtime
+ configuration mechanism on the computer—affect the way
+ in which programs present data to the user, as well as the way
+ in which they accept user input.</para>
+
+ <para>On Unix-like systems, you can check the values of the
+ locale-related runtime configuration options by running the
+ <command>locale</command> command:</para>
<screen>
$ locale
@@ -2520,32 +2522,35 @@
variables are all set to the default <literal>C</literal>
locale, but users can set these variables to specific
country/language code combinations. For example, if one were
- to set the <literal>LC_TIME</literal> variable
- to <literal>fr_CA</literal>, then programs would know to
- present time and date information formatted according a
+ to set the <literal>LC_TIME</literal> variable to
+ <literal>fr_CA</literal>, then programs would know to present
+ time and date information formatted according a
French-speaking Canadian's expectations. And if one were to
- set the <literal>LC_MESSAGES</literal> variable
- to <literal>zh_TW</literal>, then programs would know to
- present human-readable messages in Traditional Chinese.</para>
-
- <para>Setting the <literal>LC_ALL</literal> variable has the
- effect of changing every locale variable to the same value.
- The value of <literal>LANG</literal> is used as a default
- value for any locale variable that is unset.</para>
-
- <para>To see the list of available locales on a Unix system, run
- the command <command>locale -a</command>. On Windows, one can
- open the <quote>Regional and Language Options</quote> control
- panel to view and select available locales.</para>
+ set the <literal>LC_MESSAGES</literal> variable to
+ <literal>zh_TW</literal>, then programs would know to present
+ human-readable messages in Traditional Chinese. Setting the
+ <literal>LC_ALL</literal> variable has the effect of changing
+ every locale variable to the same value. The value of
+ <literal>LANG</literal> is used as a default value for any
+ locale variable that is unset. To see the list of available
+ locales on a Unix system, run the command <command>locale
+ -a</command>.</para>
+
+ <para>On Windows, locale configuration is done via the
+ <quote>Regional and Language Options</quote> control panel
+ item. There you can view and select the values of individual
+ settings from the available locales, and even customize (at a
+ sickening level of detail) several of the display formatting
+ conventions.</para>
</sect2>
<sect2 id="svn-ch7-sect-5.2">
<title>Subversion's use of locales</title>
- <para>The Subversion client, <command>svn</command>, makes use
- of the current locale in two ways. First, it notices the
- value of the <literal>LC_MESSAGES</literal> variable and
+ <para>The Subversion client, <command>svn</command>, honors the
+ current locale configuration in two ways. First, it notices
+ the value of the <literal>LC_MESSAGES</literal> variable and
attempts to print all messages in the specified language. For
example:</para>
@@ -2563,36 +2568,33 @@
may not be able to speak the particular language. In order to
produce localized messages, human volunteers must provide
translations for each language. The translations are written
- using the GNU <command>gettext</command> package, which
- results in translation <quote>modules</quote> that end
- with <filename>.mo</filename> extensions. For example, the
- German translation file is named <filename>de.mo</filename>.
- These translation files are installed somewhere on your
- system. On Unix, they typically live
- in <filename>/usr/local/share/locale/</filename>, while on
- Windows they're often found in
- the <filename>\share\locale\</filename> folder in Subversion's
+ using the GNU gettext package, which results in translation
+ modules that end with the <filename>.mo</filename> filename
+ extension. For example, the German translation file is named
+ <filename>de.mo</filename>. These translation files are
+ installed somewhere on your system. On Unix, they typically
+ live in <filename>/usr/share/locale/</filename>, while
+ on Windows they're often found in the
+ <filename>\share\locale\</filename> folder in Subversion's
installation area. Once installed, a module is named after
- the program it provides translations for. For example,
- the <filename>de.mo</filename> file may ultimately end up
- installed
- as <filename>/usr/local/share/locale/de/LC_MESSAGES/subversion.mo</filename>.
+ the program it provides translations for. For example, the
+ <filename>de.mo</filename> file may ultimately end up
+ installed as
+ <filename>/usr/share/locale/de/LC_MESSAGES/subversion.mo</filename>.
By browsing the installed <filename>.mo</filename> files, you
can see which languages the Subversion client is able to
speak.</para>
- <para>The second way in which locale is important is that it
- tells the <command>svn</command> program how to interpret your
- input. The repository stores all paths, filenames, and log
- messages in Unicode. In that sense, the repository
- is <firstterm>internationalized</firstterm>— that is,
- the repository is ready to accept input in any human language.
- The repository stores the Unicode data as UTF-8, which is a
- particular encoding of Unicode. This means, however, that the
- Subversion client is responsible for sending only UTF-8
- filenames and log messages into the repository. In order to
- do this, it must convert the data from the native locale into
- UTF-8.</para>
+ <para>The second way in which the locale is honored involves how
+ <command>svn</command> interprets your input. The repository
+ stores all paths, filenames, and log messages in Unicode,
+ encoded as UTF-8. In that sense, the repository is
+ <firstterm>internationalized</firstterm>— that is, the
+ repository is ready to accept input in any human language.
+ This means, however, that the Subversion client is responsible
+ for sending only UTF-8 filenames and log messages into the
+ repository. In order to do this, it must convert the data
+ from the native locale into UTF-8.</para>
<para>For example, suppose you create a file
named<filename>caffè.txt</filename>, and then when committing
@@ -2612,21 +2614,29 @@
contents.</para>
<sidebar>
- <title>"Error: can't recode string"</title>
-
- <para>Are you seeing this error? It means that the Subversion
- client has received a UTF-8 string from the repository, but
- the characters can't be converted to the current locale.
- For example, if your locale is <literal>en_US</literal> but
- a collaborator has committed a Japanese filename, you're
- likely to see this error when you receive the file during
- an <command>svn update</command>.</para>
+ <title>Character set conversion errors</title>
+
+ <para>While using Subversion, you might get hit with an error
+ related to character set conversions:</para>
+
+ <screen>
+svn: Can't recode string.
+</screen>
+
+ <para>The message is cryptic, but generally occurs when the
+ Subversion client has received a UTF-8 string from the
+ repository, but the characters can't be converted to the
+ current locale. For example, if your locale is
+ <literal>en_US</literal> but a collaborator has committed a
+ Japanese filename, you're likely to see this error when you
+ receive the file during an <command>svn
+ update</command>.</para>
<para>The solution is either to set your locale to something
which <emphasis>can</emphasis> represent the incoming UTF-8
data, or to change the filename or log message in the
repository. (And don't forget to slap your collaborator's
- hand; projects should decide on common languages ahead of
+ hand—projects should decide on common languages ahead of
time, so that all participants are using the same
locale.)</para>
</sidebar>
More information about the svnbook-dev
mailing list