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