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 Fri, 20 Apr 2012, Michael Kerrisk wrote:

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

The man pages should be written by people interested in writing them, of 
course.  In accordance with the GNU Coding Standards, man pages are 
secondary to the Texinfo documentation for GNU software.  They should be 
read as independent observations about the library rather than a contract 
with applications.  Independent observations are useful; differences 
between those observations and the GNU manuals (and between either and 
POSIX) can help point out areas that may be tricky or controversial.

If in doubt about a particular point, feel free to raise it on libc-alpha 
- or file a bug in Bugzilla if you think it's a bug.  I hope that anything 
the man pages describe as being a bug in current glibc also has an 
associated open bug in Bugzilla.

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

The "push" is that all information about bugs is pushed to glibc-bugs, and 
anyone concerned, for any reason, to get new information about glibc bugs 
(whether filed or fixed) can follow that, and filter it however they want.  
Man pages are not special in that regard.  It's for the man pages 
maintainers to have their own (hopefully documented) guidelines describing 
what makes a (current or former) bug worth documenting as such in a man 
page, and to track however they find convenient when bugs mentioned in man 
pages get fixed (whether with metadata in the man pages linking them to 
bugs in glibc Bugzilla, or the other way round, or some other approach).

Patches are also pushed to libc-alpha (or libc-ports) with explanations, 
and all commits go on glibc-cvs automatically.  If an explanation in a bug 
or patch posting isn't sufficient, ask questions about it.  This applies 
to whatever use you have for the information.  As far as I'm concerned, 
good explanations for bugs and patches are generally important in glibc 
development, and should benefit everyone following glibc development for 
any reason (man page maintenance being just one reason people may wish to 
follow glibc development).

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

Formerly new interfaces were added without review.  I think it's now clear 
that adding a new public (architecture-independent, at least) interface 
requires consensus that will not result from one person acting alone.  So 
if there is consensus for the above model of patches needing documentation 
for new interfaces - whether explicit, or simply implicit through patch 
reviewers requesting that a patch also update the manual - then such 
interfaces will not go in without documentation.

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