diff options
Diffstat (limited to 'doc/msgcat.n')
| -rw-r--r-- | doc/msgcat.n | 83 |
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" |