summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/msgcat.n83
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"