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

[Bruno Haible]

[CCing bug-gettext. Please drop bug-gnulib in your replies.]

Gavin Smith wrote in
<https://lists.gnu.org/archive/html/bug-gnulib/2024-12/msg00153.html>:
> I was reading a man page for gettext(3) and I wanted to know where
> the page came from.  I scrolled to the bottom of the page and there was:
> 
> GNU gettext 0.22.5                 May 2001                         GETTEXT(3)
> 
> I downloaded gettext-0.23 and checked that the string "May 2001" is also
> present in several man page sources:
> 
> ./gettext-runtime/man/bindtextdomain.3.in:.TH BINDTEXTDOMAIN 3 "May 2001" 
> "GNU gettext @VERSION@"
> ./gettext-runtime/man/textdomain.3.in:.TH TEXTDOMAIN 3 "May 2001" "GNU 
> gettext @VERSION@"
> ./gettext-runtime/man/ngettext.3.in:.TH NGETTEXT 3 "May 2001" "GNU gettext 
> @VERSION@"

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

> Can I suggest that the update date is updated along with the version number?
> This could give some reassurance that the documentation is up to date.

You can certainly suggest it. The question is really: What does "up to date"
mean for a stable API, that is part of the LI18NUX standard since ca. 2001
or 2002 ?

> These pages have been altered since 2001, for example there is a ChangeLog
> entry from 2024-11-19 mentioning some of these pages.

Yes, and on that date I changed the footer/header of these man pages to
contain "November 2024" instead of "May 2001". But that was after the 0.22.5
release, and you were looking at the man pages from 0.22.5.

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

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

Bruno