tip 499 msgcat custom preferences: documentation added

1 files changed, 85 insertions, 27 deletions

diff --git a/doc/msgcat.n b/doc/msgcat.n
index fbea20f..9074725 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -29,7 +29,9 @@ msgcat \- Tcl message catalog
 .sp
 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
 .sp
-\fB::msgcat::mcpreferences\fR
+.VS "TIP 499"
+\fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ...
+.VE "TIP 499"
 .sp
 .VS "TIP 412"
 \fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR?
@@ -54,6 +56,10 @@ msgcat \- Tcl message catalog
 .sp
 \fB::msgcat::mcforgetpackage\fR
 .VE "TIP 412"
+.sp
+.VS "TIP 499"
+\fB::msgcat::mcutil subcommand\fR ?\fIlocale\fR?
+.VS "TIP 499"
 .BE
 .SH DESCRIPTION
 .PP
@@ -145,7 +151,7 @@ The namespace of the caller is used if not explicitly specified.
 \fB::msgcat::mcpackagenamespaceget\fR
 .
 Return the package namespace of the caller.
-This command handles all cases described in section \fBObject oriented programming\fR.
+This command handles all cases described in section \fBOBJECT ORIENTED PROGRAMMING\fR.
 .PP
 .RS
 Example usage is a tooltip package, which saves the caller package namespace to update the translation each time the tooltip is shown:
@@ -169,14 +175,22 @@ proc ::tooltip::show {widget messagenamespace message} {
 .TP
 \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.  msgcat stores and compares the locale in a
+If \fInewLocale\fR is omitted, the current locale is returned, otherwise the current locale
+is set to \fInewLocale\fR.
+.PP
+.RS
+If the new locale is set to \fInewLocale\fR, the corresponding preferences are calculated and set.
+For example, if the current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR returns \fB{en_us_funky en_us en {}}\fR.
+.PP
+The same result may be acheved by \fB::msgcat::mcpreferences\fR {*}[\fB::msgcat::mcutil getpreferences\fR \fInewLocale\fR].
+.PP
+The current locale is always the first element of the list returned by \fBmcpreferences\fR.
+.PP
+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.
-.RS
 .PP
 .VS "TIP 412"
 If the locale is set, the preference list of locales is evaluated.
@@ -184,16 +198,26 @@ Locales in this list are loaded now, if not jet loaded.
 .VE "TIP 412"
 .RE
 .TP
-\fB::msgcat::mcpreferences\fR
+\fB::msgcat::mcpreferences\fR ?\fIlocale preference\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.  The list is derived from the current
-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
-returns \fB{en_us_funky en_us en {}}\fR.
+Without arguments, returns an ordered list of the locales preferred by
+the user.
+The list is ordered from most specific to least preference.
+.PP
+.VS "TIP 499"
+.RS
+A set of locale preferences may be given to set the list of locale preferences.
+The current locale is also set, which is the first element of the locale preferences list.
+.PP
+Locale preferences are loaded now, if not jet loaded.
+.PP
+As an example, the user may prefer French or English text. This may be configured by:
+.CS
+::msgcat::mcpreferences fr en {}
+.CE
+.RE
+.PP
+.VS "TIP 499"
 .TP
 \fB::msgcat:mcloadedlocales subcommand\fR ?\fIlocale\fR?
 .
@@ -284,6 +308,22 @@ Note that this routine is only called if the concerned package did not set a pac
 The calling package clears all its state within the \fBmsgcat\fR package including all settings and translations.
 .VE "TIP 412"
 .PP
+.VS "TIP 499"
+.TP
+\fB::msgcat::mcutil getpreferences\fR \fIlocale\fR
+.
+Return the preferences list of the given locale as described in section \fBLOCALE SPECIFICATION\fR.
+An example is the composition of a preference list for the bilingual region "Biel/Bienne" as a concatenation of swiss german and swiss french:
+.CS
+% concat [lrange [msgcat::mcutil getpreferences fr_CH] 0 end-1] [msgcat::mcutil getpreferences de_CH]
+fr_ch fr de_ch de {}
+.CE
+.TP
+\fB::msgcat::mcutil getsystemlocale\fR
+.
+The system locale is returned as described by the section \fBLOCALE SPECIFICATION\fR.
+.VE "TIP 499"
+.PP
 .SH "LOCALE SPECIFICATION"
 .PP
 The locale is specified to \fBmsgcat\fR by a locale string
@@ -489,7 +529,7 @@ formatting substitution is done directly.
 # human-oriented versions by \fBmsgcat::mcset\fR
 .CE
 .VS "TIP 412"
-.SH Package private locale
+.SH "PACKAGE PRIVATE LOCALE"
 .PP
 A package using \fBmsgcat\fR may choose to use its own package private
 locale and its own set of loaded locales, independent to the global
@@ -513,10 +553,22 @@ This command may cause the load of locales.
 .
 Return the package private locale or the global locale, if no package private locale is set.
 .TP
-\fB::msgcat::mcpackagelocale preferences\fR
+\fB::msgcat::mcpackagelocale preferences\fR ?\fIlocale preference\fR? ...
 .
-Return the package private preferences or the global preferences,
+With no parameters, return the package private preferences or the global preferences,
 if no package private locale is set.
+The package locale state (set or not) is not changed (in contrast to the command \fB::msgcat::mcpackagelocale set\fR).
+.PP
+.RS
+.VS "TIP 499"
+If a set of locale preferences is given, it is set as package locale preference list.
+The package locale is set to the first element of the preference list.
+A package locale is activated, if it was not set so far.
+.PP
+Locale preferences are loaded now for the package, if not jet loaded.
+.VE "TIP 499"
+.RE
+.PP
 .TP
 \fB::msgcat::mcpackagelocale loaded\fR
 .
@@ -540,7 +592,7 @@ Returns true, if the given locale is loaded for the package.
 .
 Clear any loaded locales of the package not present in the package preferences.
 .PP
-.SH Changing package options
+.SH "CHANGING PACKAGE OPTIONS"
 .PP
 Each package using msgcat has a set of options within \fBmsgcat\fR.
 The package options are described in the next sectionPackage options.
@@ -615,7 +667,7 @@ A generic unknown handler is used if set to the empty string. This consists in r
 See section \fBcallback invocation\fR below.
 The appended arguments are identical to \fB::msgcat::mcunknown\fR.
 .RE
-.SH Callback invocation
+.SH "Callback invocation"
 A package may decide to register one or multiple callbacks, as described above.
 .PP
 Callbacks are invoked, if:
@@ -630,13 +682,15 @@ If a called routine fails with an error, the \fBbgerror\fR routine for the inter
 Only exception is the callback \fBunknowncmd\fR, where an error causes the invoking \fBmc\fR-command to fail with that error.
 .PP
 .VS tip490
-.SH Object oriented programming
+.SH "OBJECT ORIENTED PROGRAMMING"
 \fBmsgcat\fR supports packages implemented by object oriented programming.
 Objects and classes should be defined within a package namespace.
 .PP
 There are 3 supported cases where package namespace sensitive commands of msgcat (\fBmc\fR, \fBmcexists\fR, \fBmcpackagelocale\fR, \fBmcforgetpackage\fR, \fBmcpackagenamespaceget\fR, \fBmcpackageconfig\fR, \fBmcset\fR and \fBmcmset\fR) may be called:
 .PP
-.SH 1) In class definition script
+.TP
+\fB1) In class definition script\fR
+.
 \fBmsgcat\fR command is called within a class definition script.
 .CS
 namespace eval ::N2 {
@@ -645,7 +699,9 @@ namespace eval ::N2 {
 }
 .CE
 .PP
-.SH 2) method defined in a class
+.TP
+\fB2) method defined in a class\fR
+.
 \fBmsgcat\fR command is called from a method in an object and the method is defined in a class.
 .CS
 namespace eval ::N3Class {
@@ -657,7 +713,9 @@ namespace eval ::N3Class {
 }
 .CE
 .PP
-.SH 3) method defined in a classless object
+.TP
+\fB3) method defined in a classless object\fR
+.
 \fBmsgcat\fR command is called from a method of a classless object.
 .CS
 namespace eval ::N4 {
@@ -670,7 +728,7 @@ namespace eval ::N4 {
 .CE
 .PP
 .VE tip490
-.SH Examples
+.SH EXAMPLES
 Packages which display a GUI may update their widgets when the global locale changes.
 To register to a callback, use:
 .CS
@@ -736,9 +794,9 @@ proc ::tcl::clock::LocalizeFormat { locale format } {
 .PP
 The message catalog code was developed by Mark Harrison.
 .SH "SEE ALSO"
-format(n), scan(n), namespace(n), package(n)
+format(n), scan(n), namespace(n), package(n), oo::class(n), oo::object
 .SH KEYWORDS
-internationalization, i18n, localization, l10n, message, text, translation
+internationalization, i18n, localization, l10n, message, text, translation, class, object
 .\" Local Variables:
 .\" mode: nroff
 .\" End: