Re: The future of the manual (was Re: [PATCH] Add getcpu)

[Joseph Myers <joseph at codesourcery dot com>]

On Wed, 5 Dec 2018, Zack Weinberg wrote:

> On Wed, Dec 5, 2018 at 3:43 PM Joseph Myers <joseph@codesourcery.com> wrote:
> > On Wed, 5 Dec 2018, Florian Weimer wrote:
> >
> > > We have a parallel discussion about a new requirement that all new
> > > functions must have documentation in the manual.
> >
> > It's not a new requirement at all.  Documenting new interfaces was added
> > to <https://sourceware.org/glibc/wiki/Contribution%20checklist> on
> > 2012-04-17.
> 
> I get the impression that Florian either believes that the existing
> manual is no longer useful, or has some kind of principled objection
> to adding new material to it.  Either would be reason to open a
> new_discussion about changing this rule.
> 
> Florian, would you mind, at your convenience, explaining why you do
> not want to add new material to the manual?

I would also suggest that people reread the previous discussion 
<https://sourceware.org/ml/libc-alpha/2012-04/threads.html#00315> 
(especially Roland's comments 
<https://sourceware.org/ml/libc-alpha/2012-04/msg00988.html>).

I see then I was listing possible exceptions to requiring documentation 
for functions from external standards and direct wrappers round system 
calls <https://sourceware.org/ml/libc-alpha/2012-04/msg00724.html>.  I 
don't now think such exceptions are generally a good idea, but there may 
be cases where we can't usefully say much about semantics beyond that a 
function calls the Linux system call of the same name (plus the 
information about things that aren't part of the syscall interface) - say 
if we add a wrapper for the bpf syscall (bug 18271).

For the bulk of new functions added since that discussion coming from 
external standards - for example, the C11 threads functions and the TS 
18661 floating-point functions - documentation *has* been added to the 
glibc manual (and in many cases not to Linux man-pages).

-- 
Joseph S. Myers
joseph@codesourcery.com