This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]