1 files changed, 57 insertions, 20 deletions
diff --git a/doc/msgcat.n b/doc/msgcat.n
index a212b2f..bae6dbe 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -4,10 +4,8 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" SCCS: @(#) msgcat.n
-'\" 
+.TH "msgcat" n 1.5 msgcat "Tcl Bundled Packages"
 .so man.macros
-.TH "msgcat" n 1.4 msgcat "Tcl Bundled Packages"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -15,7 +13,7 @@ msgcat \- Tcl message catalog
 .SH SYNOPSIS
 \fBpackage require Tcl 8.5\fR
 .sp
-\fBpackage require msgcat 1.4.2\fR
+\fBpackage require msgcat 1.5\fR
 .sp
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 .sp
@@ -31,7 +29,13 @@ msgcat \- Tcl message catalog
 .sp
 \fB::msgcat::mcmset \fIlocale src-trans-list\fR
 .sp
-\fB::msgcat::mcunknown \fIlocale src-string\fR
+.VS "TIP 404"
+\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR?
+.sp
+\fB::msgcat::mcflmset \fIsrc-trans-list\fR
+.VE "TIP 404"
+.sp
+\fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
@@ -133,12 +137,33 @@ translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly
 faster than multiple invocations of \fB::msgcat::mcset\fR. The function
 returns the number of translations set.
 .TP
-\fB::msgcat::mcunknown \fIlocale src-string\fR
+\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR?
+.VS "TIP 404"
+Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the
+current namespace for the locale implied by the name of the message catalog
+being loaded via \fB::msgcat::mcload\fR.  If \fItranslate-string\fR is not
+specified, \fIsrc-string\fR is used for both.  The function returns
+\fItranslate-string\fR.
+.VE "TIP 404"
+.TP
+\fB::msgcat::mcflmset \fIsrc-trans-list\fR
+.VS "TIP 404"
+Sets the translation for multiple source strings in \fIsrc-trans-list\fR in
+the current namespace for the locale implied by the name of the message
+catalog being loaded via \fB::msgcat::mcload\fR. \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?}
+\fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations
+of \fB::msgcat::mcflset\fR. The function returns the number of translations set.
+.VE "TIP 404"
+.TP
+\fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR?
 .
 This routine is called by \fB::msgcat::mc\fR in the case when
 a translation for \fIsrc-string\fR is not defined in the
 current locale.  The default action is to return
-\fIsrc-string\fR.  This procedure can be redefined by the
+\fIsrc-string\fR passed by format if there are any arguments.  This
+procedure can be redefined by the
 application, for example to log error messages for each unknown
 string.  The \fB::msgcat::mcunknown\fR procedure is invoked at the
 same stack context as the call to \fB::msgcat::mc\fR.  The return value
@@ -177,11 +202,14 @@ to extract its parts.  The initial locale is then set by calling
 language[_country][_modifier]
 .CE
 .PP
-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
+On Windows and Cygwin, if none of those environment variables is set,
+msgcat will attempt to extract locale information from the registry.
+From Windows Vista on, the RFC4747 locale name "lang-script-country-options"
+is transformed to the locale as "lang_country_script" (Example:
+sr-Latn-CS -> sr_cs_latin). For Windows XP, the language id is
+transformed analoguously (Example: 0c1a -> sr_yu_cyrillic).
+If all these attempts to discover an initial locale from the user's
+environment fail, msgcat defaults to an initial locale of
 .QW C .
 .PP
 When a locale is specified by the user, a
@@ -212,7 +240,7 @@ For example, executing the code
 .CS
 \fB::msgcat::mcset\fR en hello "hello from ::"
 namespace eval foo {
-   \fB::msgcat::mcset\fR en hello "hello from ::foo"
+    \fB::msgcat::mcset\fR en hello "hello from ::foo"
 }
 puts [\fB::msgcat::mc\fR hello]
 namespace eval foo {puts [\fB::msgcat::mc\fR hello]}
@@ -241,11 +269,11 @@ locale) the code
 \fB::msgcat::mcset\fR en m2 ":: message2"
 \fB::msgcat::mcset\fR en m3 ":: message3"
 namespace eval ::foo {
-   \fB::msgcat::mcset\fR en m2 "::foo message2"
-   \fB::msgcat::mcset\fR en m3 "::foo message3"
+    \fB::msgcat::mcset\fR en m2 "::foo message2"
+    \fB::msgcat::mcset\fR en m3 "::foo message3"
 }
 namespace eval ::foo::bar {
-   \fB::msgcat::mcset\fR en m3 "::foo::bar message3"
+    \fB::msgcat::mcset\fR en m3 "::foo::bar message3"
 }
 namespace import \fB::msgcat::mc\fR
 puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"
@@ -285,15 +313,15 @@ cause peculiar behavior, such as marking the message file as
 .QW hidden
 on Unix file systems.
 .IP [3]
-The file contains a series of calls to \fBmcset\fR and
-\fBmcmset\fR, setting the necessary translation strings
+The file contains a series of calls to \fBmcflset\fR and
+\fBmcflmset\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:
 .PP
 .CS
 namespace eval ::mypackage {
-   \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!"
+    \fB::msgcat::mcflset\fR "Free Beer!" "Cerveza Gracias!"
 }
 .CE
 .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"
@@ -335,7 +363,16 @@ format "In location %2\e$s we produced %1\e$d units" $num $city
 .CE
 .PP
 Similarly, positional parameters can be used with \fBscan\fR to
-extract values from internationalized strings.
+extract values from internationalized strings. Note that it is not
+necessary to pass the output of \fB::msgcat::mc\fR to \fBformat\fR
+directly; by passing the values to substitute in as arguments, the
+formatting substitution is done directly.
+.PP
+.CS
+\fBmsgcat::mc\fR {Produced %1$d at %2$s} $num $city
+# ... where that key is mapped to one of the
+# human-oriented versions by \fBmsgcat::mcset\fR
+.CE
 .SH CREDITS
 .PP
 The message catalog code was developed by Mark Harrison.