Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Rich Felker <dalias@aerifal.cx>]

On Sun, Jul 07, 2013 at 12:04:04AM +0100, Justin Cormack wrote:
> > > On a slightly related note, would you be interested in patches for the
> > > Linux manpages briefly documenting places where musl differs from glibc
> > > (in the NOTES section, along the same lines as the notes about
> libc4/libc5)?
> >
> > Historically, man-pages has primarily documented glibc + syscalls, but
> > there's nothing firm about that. It's more been about limited time
> > resources and the fact that glibc is the most widely used libc. I'd
> > have no objection to musl-specific notes in the man-pages. Perhaps a
> > patch to libc(7) would be a good place to start.

I'm not sure how much effort would be involved. My ideal outcome would
be for the man pages to evolve to document what applications can
_portably_ expect from the interfaces, with appropriate notes on
caveats where certain libc versions or kernel versions give you
less-than-conforming behavior, and where nonstandard extensions are
available. However my feeling is that this would be a very big project
and I'm not sure if Michael would want to go in that direction. I do
think it would greatly improve the quality of Linux software
development, though.

> The man(2) section is rather glibc specific and makes the syscall details
> rather subsidiary. I will try to send some patches if these would be
> welcome.

I think it's an error to have anything glibc-specific in section 2 of
the manual, which should be documenting the kernel, not userspace.
What would be useful in the section 2 man pages is to document where
the syscall is insufficient to provide POSIX semantics, which are left
to userspace to provide. Such section 2 pages could then have
corresponding section 3 pages that document the library behavior.

Rich