Re: gettext man pages have old date at bottom (May 2001)

[Bruno Haible]

Gavin Smith wrote:
> > I don't see man pages from "Linux man pages" for the *gettext functions.
> > So, the only actual source for these man pages are from GNU gettext.
> 
> I had wanted to know where these manpages came from and I knew that
> Linux man pages was a possibility as they often document glibc functions.
> They do provide manpages for gettext but they are propagated from the
> ones coming from the gettext project.
> 
> https://man7.org/linux/man-pages/man3/gettext.3.html

I see. That is consistent with the absence of a gettext.3 file in the man-pages
git repository (which is where I looked).

> The glibc Texinfo manual is not so good.  LANGUAGE is mentioned here:
> 
> https://www.gnu.org/software/libc/manual/html_node/Locale-Categories.html
> 
>   When developing the message translation functions it was felt that the
>   functionality provided by the variables above is not sufficient. For
>   example, it should be possible to specify more than one locale name. Take
>   a Swedish user who better speaks German than English, and a program
>   whose messages are output in English by default. It should be possible
>   to specify that the first choice of language is Swedish, the second
>   German, and if this also fails to use English. This is possible with
>   the variable LANGUAGE. For further description of this GNU extension
>   see User influence on gettext.
> 
> This refers you to:
> 
> https://www.gnu.org/software/libc/manual/html_node/Using-gettextized-software.html
> 
> This section is quite long-winded and doesn't actually say anything about
> the effect of a "C" locale.  In fact, the whole section in the glibc
> manual on gettext is quite long-winded.

Yes, it is a pity that entire sections of the glibc manual are out-of-date.

> The documentation in the "gettext" manual ((gettext)The LANGUAGE variable)
> is good as well, although this manual does not document the C functions
> ('gettext', 'dgettext' etc.) themselves, so you have to combine information
> from both the "libc" and "gettext" manuals to fully understand the
> behaviour of the gettext function.

Good remark. I've registered a TODO item about it here:
https://savannah.gnu.org/bugs/?66593

> I am just a little unclear on the difference between locale categories
> and environment variables:
> 
>      Note: The variable ‘LANGUAGE’ is ignored if the locale is set to ‘C’.
>   In other words, you have to first enable localization, by setting ‘LANG’
>   (or ‘LC_ALL’) to a value other than ‘C’, before you can use a language
>   priority list through the ‘LANGUAGE’ variable.
> 
> In this paragraph, LANGUAGE is a environment variable, so it appears that
> this refers to setting the LANG and/or the LC_ALL environment variables.

Correct.

> However, setting these is neither necessary nor sufficient for LANGUAGE to
> work - what matters is the locale setting itself (LC_MESSAGES, althouugh
> it may be different for dcgettext where you can give a different locale
> category). The following does not translate the string even though LC_ALL
> is set:
> 
>         setlocale (LC_ALL, "C");
>         bindtextdomain ("texinfo_document",
>                         "GIT/tp/LocaleData");
>         textdomain("texinfo_document");
>         setenv ("LC_ALL", "en_GB.UTF-8", 1);
>         setenv ("LANGUAGE", "de", 1);
>         printf ("%s\n", gettext ("Table of contents"));
> 
> (For this test translation files were present in the directory
> given as an argument to 'bindtextdomain'.)
> 
> The following does translate the string even though both the LC_ALL
> and LANG environment variables are set to "C", because the LC_MESSAGES 
> locale is set:
> 
>         setlocale (LC_ALL, "C");
>         bindtextdomain ("texinfo_document",
>                         "GIT/tp/LocaleData");
>         textdomain("texinfo_document");
>         setenv ("LC_ALL", "C", 1);
>         setenv ("LANG", "C", 1);
>         setlocale (LC_MESSAGES, "en_GB.UTF-8");
>         setenv ("LANGUAGE", "de", 1);
>         printf ("%s\n", gettext ("Table of contents"));

Here you are back at the problem we discussed in
<https://lists.gnu.org/archive/html/bug-gettext/2024-11/msg00050.html>.

> I understand that this pararaph is written from the perspective of
> a user using a gettextized program and setting these environment variables
> will indirectly lead to the LC_MESSAGES locale being set for the program.
> 
> I tried editing the paragraph; maybe you could use similar wording:
> 
>      Note: The variable ‘LANGUAGE’ is ignored if the locale is set to ‘C’.
>   In other words, the user of a gettext-enabled program needs to
>   have ‘LANG’ (or ‘LC_ALL’) set in their environment to enable localization.
>   The program in turn uses these variables for the relevant locale category
>   (almost always LC_MESSSAGES).

This paragraph is in chapter "The User's View"
https://www.gnu.org/software/gettext/manual/html_node/Users.html , which
is written from the perspective of a user, not from a programmer. Therefore
wording like "the user of a gettext-enabled program" would be bloat here.

I plan to improve the doc structure w.r.t. personas/perspectives. (What I
don't like is lengthy sections that address the needs of different personas
in a mixed way.) This particular chapter is already as good as it can get.

Bruno