This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH] Fix up LD_* vars behaviour
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.
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, 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.)
> (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).
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?)
--
Joseph S. Myers
joseph@codesourcery.com