Re: Request for volunteers

[Rich Felker <dalias@aerifal.cx>]

On Sun, Jun 30, 2013 at 10:13:23PM -0500, Rob Landley wrote:
> On 06/30/2013 07:13:45 AM, Rich Felker wrote:
> >On Sun, Jun 30, 2013 at 01:02:03PM +0200, Daniel Cegiełka wrote:
> >> Rich, you missed something:
> >>
> >> 6. Man pages for musl. We need to describe the functions and
> >> namespaces in header files.
> >
> >This is a good topic for discussion. My documentation goal for 1.0 has
> >been aligned with the earlier docs outline proposal I sent to the list
> >a while back. Full man pages would be a much bigger task, and it's not
> >even something a volunteer could do without some major collaboration
> >with people who have a detailed understanding of every function in
> >musl. (Sadly, wrong man pages are probably worse than no man pages.)
> 
> Michael Kerrisk does man pages. The best thing to do is feed him
> information about musl-specific stuff. He can probably do some kind
> of inline notation in his (docbook?) masters to make musl versions
> and glibc versions.
> 
> Reinventing this wheel would suck.

Well for the standard functions, I really like the 3p versions better
than the "Linux" versions. The Linux man pages tend to have a lot of
historical cruft -- things like recommending the wrong headers to get
the function, the wrong error codes for certain conditions, etc. --
and I think auditing them for agreement with POSIX and with musl would
be a fairly major task in itself.

> >What might be better for the near future is to get the POSIX man pages
> >project updated to match POSIX-2008+TC1 so that users of musl who want
> >man pages for libc functions can install them and have them match the
> >current version.
> 
> I note that the guy who did the posix man pages ten years ago was:
> Michael Kerrisk.

Maybe someone should contact him about all the stuff we're discussing.

> (Honestly, posix seems to be slipping into some kind of dotage. One

Overall POSIX is going way up in quality, adopting extensions that are
widespread and very useful, and fixing issues that make it impossible
to write correct programs or libraries using certain features. I don't
agree with every single decision made, but that's the way the world
works.

> if its driving forces these days is Jorg Schilling. Let that sink in
> for a bit.)

I haven't seen any abuse by Schilly of his role in the standards
process. The behavior I would call abuse of power (mainly, the way the
C locale issue was treated with knee-jerk reacionary attitudes and
shut-down of rational discussion) has come from others but not him.
I'm not a fan of his fandom of Solaris, be he's not even been pushing
a Solaris agenda as far as I can tell.

Anyway, saying to beware of POSIX because Schilly likes POSIX is like
saying not to eat donuts because Schilly likes donuts...

> >Separate man pages could then be made for nonstandard
> >functions or functions that require significant implementation
> >specific documentation, possibly based on the Linux man pages project,
> >but with glibc-specific information just removed (for functions that
> >are predominantly kernel-level) or changed (where documenting musl
> >semantics matters).
> 
> Interface with the linux man pages project. They don't have strong
> glibc loyalty, they're just trying to document what people actually
> use.

Yes, I think the hardest part will be convincing them that people use
musl, at least one the scale that makes it worth noting and including
in man pages that are installed on every single Linux system. But
hopefully my concern ends up being unfounded. :-)

Rich