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

[Michael Kerrisk <mtk.manpages@gmail.com>]

Rich,

On 07/07/13 02:03, Rich Felker wrote:
> 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, 

This is what the man pages endeavor to do. (I consider cases where 
non-portable behavior is not clearly indicated to be bugs.)

> with appropriate notes on
> caveats where certain libc versions or kernel versions give you
> less-than-conforming behavior, and where nonstandard extensions are
> available. 

That's more or less what the pages do, with the proviso that "certain
libc versions" currently means just glibc, and in a few odd cases, 
ancient Linux libc.

> 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

("useful" to who? Few users care about the naked 
syscall behavior.)

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

See https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source
I think it would be a retrograde step to split syscall pages into 
Sections 2 and 3. Users want to get the documentation in one place.
Note that the approach in man-pages (consolidating info on the syscall 
plus any libc additions in one page) is not unique to Linux. From some
(offlist) discussions with the BSD man pages maintainers, it appears
that at least some (all?) of the BSDs do the same. 

Cheers,

Michael