1 files changed, 55 insertions, 28 deletions
diff --git a/doc/msgcat.n b/doc/msgcat.n
index dddf499..2fb5591 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -15,7 +15,7 @@ msgcat \- Tcl message catalog
 .SH SYNOPSIS
 \fBpackage require Tcl 8.2\fR
 .sp
-\fBpackage require msgcat 1.2\fR
+\fBpackage require msgcat 1.3\fR
 .sp
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 .sp
@@ -80,37 +80,46 @@ fixed width (which will be the width of the widest button).
 \fB::msgcat::mclocale \fR?\fInewLocale\fR?  
 This function sets the locale to \fInewLocale\fR.  If \fInewLocale\fR
 is omitted, the current locale is returned, otherwise the current locale
-is set to \fInewLocale\fR.
-The initial locale defaults to the locale specified in
-the user's environment.  See \fBLOCALE AND SUBLOCALE SPECIFICATION\fR
+is set to \fInewLocale\fR.  msgcat stores and compares the locale in a
+case-insensitive manner, and returns locales in lowercase.
+The initial locale is determined by the locale specified in
+the user's environment.  See \fBLOCALE SPECIFICATION\fR
 below for a description of the locale string format.
 .TP
 \fB::msgcat::mcpreferences\fR
 Returns an ordered list of the locales preferred by
 the user, based on the user's language specification.
 The list is ordered from most specific to least
-preference.  If the user has specified LANG=en_US_funky,
-this procedure would return {en_US_funky en_US en}.
+preference.  The list is derived from the current
+locale set in msgcat by \fBmsgcat::mclocale\fR, and
+cannot be set independently.  For example, if the
+current locale is en_US_funky, then \fBmsgcat::mcpreferences\fR
+returns {en_US_funky en_US en}.
 .TP
 \fB::msgcat::mcload \fIdirname\fR
 Searches the specified directory for files that match
-the language specifications returned by \fB::msgcat::mcpreferences\fR.
-Each file located is sourced.  The file extension is ``.msg''.
-The number of message files which matched the specification
+the language specifications returned by \fB::msgcat::mcpreferences\fR,
+extended by the file extension ``.msg''.  Each matching file is 
+read in order, assuming a UTF-8 encoding.  The file contents are
+then evaluated as a Tcl script.  This means that non-Latin characters
+may be present in the message file either directly in their UTF-8
+encoded form, or by use of the backslash-u quoting recognized by Tcl
+evaluation.  The number of message files which matched the specification
 and were loaded is returned.
 .TP
 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
 Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR
-in the specified \fIlocale\fR.  If \fItranslate-string\fR is not
-specified, \fIsrc-string\fR is used for both.  The function
-returns \fItranslate-string\fR.
+in the specified \fIlocale\fR and the current namespace.  If
+\fItranslate-string\fR is not specified, \fIsrc-string\fR is used
+for both.  The function returns \fItranslate-string\fR.
 .TP
 \fB::msgcat::mcmset \fIlocale src-trans-list\fR
 Sets the translation for multiple source strings in
-\fIsrc-trans-list\fR in the specified \fIlocale\fR.
+\fIsrc-trans-list\fR in the specified \fIlocale\fR and the current
+namespace.
 \fIsrc-trans-list\fR must have an even number of elements and is in
 the form {\fIsrc-string translate-string\fR ?\fIsrc-string
-translate-string ...\fR?} \fBmcsetcat::mcmset\fR can be significantly
+translate-string ...\fR?} \fBmsgcat::mcmset\fR can be significantly
 faster than multiple invocations of \fBmsgcat::mcset\fR. The function
 returns the number of translations set.
 .TP
@@ -125,22 +134,35 @@ same stack context as the call to \fB::msgcat::mc\fR.  The return vaue
 of \fB::msgcat::mcunknown\fR is used as the return vaue for the call
 to \fB::msgcat::mc\fR.  
 
-.SH "LOCALE AND SUBLOCALE SPECIFICATION"
+.SH "LOCALE SPECIFICATION"
 .PP
-The locale is specified by a locale string.
+The locale is specified to \fBmsgcat\fR by a locale string
+passed to \fB::msgcat::mclocale\fR.
 The locale string consists of
 a language code, an optional country code, and an optional
 system-specific code, each separated by ``_''.  The country and language
 codes are specified in standards ISO-639 and ISO-3166.
-For example, the locale ``en'' specifies English and
- ``en_US'' specifes  U.S. English.
+For example, the locale ``en'' specifies English and ``en_US'' specifies
+U.S. English.
 .PP
-The locale defaults to the value in \fBenv(LANG)\fR at the time the
-\fBmsgcat\fR package is loaded.  On Windows, if \fBenv(LANG)\fR is not
-set, the package will attempt to extract locale information from the
-registry.  If it cannot find this information in the registry, or on
-non-Windows platforms when \fBenv(LANG)\fR is not defined, the
-locale defaults to ``C''.
+When the msgcat package is first loaded, the locale is initialized
+according to the user's environment.  The variables \fBenv(LC_ALL)\fR,
+\fBenv(LC_MESSAGES)\fR, and \fBenv(LANG)\fR are examined in order.
+The first of them to have a non-empty value is used to determine the
+initial locale.  The value is parsed according to the XPG4 pattern
+.CS
+language[_country][.codeset][@modifier]
+.CE
+to extract its parts.  The initial locale is then set by calling
+\fBmsgcat::mclocale\fR with the argument 
+.CS
+language[_country][_modifier]
+.CE
+On Windows, if none of those environment variables is set, msgcat will
+attempt to extract locale information from the
+registry.  If all these attempts to discover an initial locale
+from the user's environment fail, msgcat defaults to an initial
+locale of ``C''.
 .PP
 When a locale is specified by the user, a ``best match'' search is
 performed during string translation.  For example, if a user specifies
@@ -177,7 +199,7 @@ then the parent of the current namespace, and so on until
 the global namespace is reached.  This allows child namespaces
 to "inherit" messages from their parent namespace.
 .PP
-For example, executing the code
+For example, executing (in the ``en'' locale) the code 
 .CS
 mcset en m1 ":: message1"
 mcset en m2 ":: message2"
@@ -214,10 +236,15 @@ es.msg    -- spanish
 en_UK.msg -- UK English
 .CE
 .IP [3]
-The file contains a series of calls to mcset, setting the
-necessary translation strings for the language. For example:
+The file contains a series of calls to \fBmcset\fR and
+\fBmcmset\fR, setting the necessary translation strings
+for the language, likely enclosed in a \fBnamespace eval\fR
+so that all source strings are tied to the namespace of
+the package. For example, a short \fBes.msg\fR might contain:
 .CS
-::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"
+namespace eval ::mypackage {
+    ::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"
+}
 .CE
 
 .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"