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

[Gavin Smith]

On Sun, Dec 22, 2024 at 01:53:56PM +0100, Bruno Haible wrote:
> [CCing bug-gettext. Please drop bug-gnulib in your replies.]

(Apologies for sending to the wrong list.)

> Yes, it is like this. These APIs have not changed since 2001. The manpages
> have not changed either.

I see, that was my mistake.  I realise that the dates were updated on the
manpages that had actually changed.  There is no problem then.

> > For gettext, there is some confusion about where its documentation is
> > ("libc" Texinfo manual from glibc, "gettext" Texinfo manual, man pages from
> > gettext, also man pages from "Linux man pages" which come from gettext), 
> > with
> > some of the manuals more detailed or comprensive than others.  Having 
> > correct
> > dates could reduce the confusion slightly.
> 
> Generally, for GNU documentation, Texinfo manuals are the preferred reference,
> and man pages are provided merely for convenience. (Why? Try "man bash", which
> is 278 pages long, and consider how usable that is.)
> 
> 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

> Regarding the Texinfo documentation, yes there are both the libc manual and 
> the
> gettext manual. Similarly to how regular expressions are described in several
> GNU manuals. Is it good or is it bad to have partial redundancy? Hard to 
> tell...

It's bad when some of the documentation is bad.  For example, I had been
looking for documentation of the LANGAUGE variable, and the effect of
using it in the "C" locale.  This is clearly and succinctly explained in
"man 3 gettext":

  If the LANGUAGE environment variable is set to a  nonempty  value,  and
  the  locale  is not the "C" locale, the value of LANGUAGE is assumed to
  contain a colon separated list of locale names. The functions will  at‐
  tempt to look up a translation of msgid in each of the locales in turn.
  This is a GNU extension.

  In the "C" locale, or if none of the used catalogs contain  a  transla‐
  tion  for  msgid,  the gettext, dgettext and dcgettext functions return
  msgid.

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.

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.

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.
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"));

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).