diff options
| -rw-r--r-- | doc/msgcat.n | 32 |
1 files changed, 20 insertions, 12 deletions
diff --git a/doc/msgcat.n b/doc/msgcat.n index d5aa1c9..aaa8b4f 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -33,7 +33,6 @@ msgcat \- Tcl message catalog .sp \fB::msgcat::mcunknown \fIlocale src-string\fR .BE - .SH DESCRIPTION .PP The \fBmsgcat\fR package provides a set of functions @@ -95,7 +94,8 @@ locale set in msgcat by \fB::msgcat::mclocale\fR, and cannot be set independently. For example, if the current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR .VS 1.4 -returns \fB{en_US_funky en_US en {}}\fR. +returns +.QW "\fBen_US_funky en_US en {}\fR" . .VE 1.4 .TP \fB::msgcat::mcload \fIdirname\fR @@ -122,8 +122,9 @@ Sets the translation for multiple source strings in \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?} \fB::msgcat::mcmset\fR can be significantly +the form +.QW "\fIsrc-string translate-string\fR ?\fIsrc-string translate-string ...\fR?}" . +The \fB::msgcat::mcmset\fR command can be significantly faster than multiple invocations of \fB::msgcat::mcset\fR. The function returns the number of translations set. .TP @@ -216,8 +217,9 @@ hello from ::foo When searching for a translation of a message, the message catalog will search first the current namespace, 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. +the global namespace is reached. This allows child namespaces to +.QW inherit +messages from their parent namespace. .PP For example, executing (in the .QW en @@ -255,6 +257,7 @@ The message file name is a msgcat locale specifier (all lowercase) followed by .QW .msg . For example: +.RS .CS es.msg -- spanish en_gb.msg -- United Kingdom English @@ -267,17 +270,20 @@ cause peculiar behavior, such as marking the message file as .QW hidden on Unix file systems. .VE 1.4 +.RE .IP [3] 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: +.RS .CS namespace eval ::mypackage { \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!" } .CE +.RE .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" .PP If a package is installed into a subdirectory of the @@ -289,12 +295,13 @@ During package installation, create a subdirectory .IP [2] Copy your *.msg files into that directory. .IP [3] - Add the following command to your package -initialization script: +Add the following command to your package initialization script: +.RS .CS # load language files, stored in msgs subdirectory \fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs] .CE +.RE .SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS" .PP It is possible that a message string used as an argument @@ -307,8 +314,7 @@ format "We produced %d units in location %s" $num $city format "In location %s we produced %d units" $city $num .CE .PP -This can be handled by using the positional -parameters: +This can be handled by using the positional parameters: .CS format "We produced %1\\$d units in location %2\\$s" $num $city format "In location %2\\$s we produced %1\\$d units" $num $city @@ -316,12 +322,14 @@ format "In location %2\\$s we produced %1\\$d units" $num $city .PP Similarly, positional parameters can be used with \fBscan\fR to extract values from internationalized strings. +.PP +\fINote:\fR for the specific case of formatting a string, you should +take advantage of the fact that the \fB::msgcat::mc\fR command already +passes its string through \fBformat\fR internally. .SH CREDITS .PP The message catalog code was developed by Mark Harrison. - .SH "SEE ALSO" format(n), scan(n), namespace(n), package(n) - .SH KEYWORDS internationalization, i18n, localization, l10n, message, text, translation |