Re: [PATCH] Fix up LD_* vars behaviour

[Michael Kerrisk <mtk dot manpages at gmail dot com>]

Joseph,

On Fri, Apr 20, 2012 at 4:18 AM, Joseph S. Myers
<joseph@codesourcery.com> wrote:
> On Thu, 12 Apr 2012, Carlos O'Donell wrote:
>
>> (a) Link to the man-pages project from the glibc documentation page:
>> http://www.gnu.org/software/libc/documentation.html, and consider the
>> man-pages as an alternative source of information for the interfaces
>> defined in glibc.
>
> Yes.
>
>> (b) Work closely with the project to keep key man pages updated e.g.
>> ld.so. For example we've just added a new --inhibit-cache that will be
>> out with 2.16.
>
> I think the right way of doing this is to make sure that such user-visible
> features are mentioned in the NEWS file. ?That way it's an easy source for
> man-pages maintainers to see what needs new pages added for a new glibc
> release.

But at that point the question becomes: who should write and review
the man pages (and what legitimacy does that documentation have)?

If you're considering that man-pages updates are independent of glibc
(i.e., updates are done by people associated primarily with man
pages), then we end up with the current de facto situation: man-pages,
although far more complete than the glibc manual, are not regarded as
in any way authoritative by glibc maintainers.

If you're considering that the glibc maintainers would have a role in
updating man pages, then the above mechanism creates a lot of
impedance. (I.e., the picture I have is that after the fact someone on
the man-pages project sees information in NEWS, goes to some effort to
find the appropriate glibc contributor, and then asks them if they'd
assist in updating the man page).

> In addition, we should keep to the recent practice that if you're fixing a
> bug you should first make sure it's filed in Bugzilla. ?man-pages
> maintainers should watch glibc-bugs,

The thing is, if there's interest in having man pages up to date with
respect to bugs, then it would be very much more efficient if this was
a "push" activity (glibc maintainer fixing a userspace-visible bug
informs man-pages/writes a man-pages patch), rather than a "pull"
activity (man-pages maintainer looks at bug fix, assesses whether it's
a user visible change, and then updates man page, possibly in
consultation with glibc maintainer).

> both to consider new bug reports for
> whether they are worth mentioning in BUGS sections of pages, and for
> considering whether bug fixes require an update to such sections. ?(I
> don't know whether the existing lists of bugs in NEWS have been used for
> the purpose of updating BUGS sections, though they could be used for that
> if there is a backlog where fixes weren't carefully watched for updates.)

No, the existing lists of bugs in NEWS has not to date been used as a
source for BUGS sections in man-pages.

>> (b) Make it part of our contribution checklist to update the
>> associated linux man-page e.g. "Where is your linux man-pages update?"
>> (http://sourceware.org/glibc/wiki/Contribution%20checklist).
>
> The most I think is appropriate there is "Consider also updating Linux
> man-pages where applicable.".
>
> My view of when glibc's own documentation (not that in a separate project)
> should be updated by a patch is: it is desirable for all public interfaces
> in glibc to be documented in the glibc manual. ?This should be considered
> required for all new functions that do not come from a standard such as
> ISO C or POSIX, and are not just direct wrappers round system calls,
> unless they form part of a group with existing functions none of which are
> documented. ?Even in those cases (functions from external standards,
> direct wrappers round system calls, and functions from existing
> undocumented groups of functions), documentation is still desirable (but I
> don't want to require it to be added in order to add the function).

To date, the above has been far from glibc practice. Many
glibc-specific interfaces are not documented in the manual; most of
the others are incompletely documented. I'm kind of doubtful that this
will change. And it's worth reiterating a point I made in my initial
reply to Roland in this thread: when it comes to the many (many)
interfaces (or details of interfaces) that are undocumented in the
glibc manual, the users of glibc have no predictable contract about
behavior. That makes life rather difficult for userspace.

> Note that we are conservative about adding public interfaces that are not
> from external standards or direct system call wrappers.
>
> (Does the Linux kernel require manpage updates in order to add a new
> system call?)

There's not a rigid requirement, but there's increasingly strong
social pressure (key maintainers who will prod code contributors to
involve man-pages).

Cheers,

Michael