[CC += linux-man@ , obviously] Hello Carlos, et al. On Fri, 22 May 2020 at 17:34, Carlos O'Donell <carlos@xxxxxxxxxx> wrote: > > Michael, > > Could we create a process by which we might incrementally mark linux > man pages as authoritative for a given C library implementation and > at the same time encourage more C library community involvement in the > development and maintenance of the linux man pages? > > I'm including Rich Felker the main musl developer, because I think > this topic applies to musl, and the linux man pages already contain > some markup for other C libraries. > > Let me paint a picture of the future (what else are Fridays for): > > * The project manual is a task-oriented document that describes how > to use APIs together to achieve certain purposes. We update the > manual based on new uses and complex task-oriented requirements > e.g. how do you effectively use clone, or vfork, or unshare with > all the right APIs to do something useful like starting your own > container by hand. > > * The linux man pages are the authoritative reference for all the > APIs that are derived from ISO C, POSIX, BSD, and other systems. > I say "derived" because we do not follow them strictly, but instead > derive from them and deviate where appropriate given the underlying > kernel. > > * A process exists to mark a manual page as authoritative for the C > library API it implements e.g. Authoritative for glibc, or musl, > or uclibc. Such markup means a developer from that project should > review patches to that page in a timely fashion to agree that we > haven't crossed any implementation boundary e.g. documented something > that is not guaranteed. Such review needs a timeout as part of the > agreement. > > * The C libraries have as a goal to update the API documentation in > the linux man page as the authoritative source of the API reference > and make it part of their submission process. Yes, this involves > committing across two projects, and some good coordination. > > In such a future we have the following assurances: > > * More developers familiar with C library implementations working on > the linux man pages project, and providing continuity of care for > the project. > > * The linux man pages project accepts certain authors as needing > to review, in a timely fashion, certain changes to certain marked > man pages. > > * The downstream C library implementations are all incentivized > to contribute to the existing linux man pages project and support > that effort, thus growing the quality and coverage of the man pages. > > * We reduce duplication of efforts in documenting the APIs as they > are derived, with differences, from ISO C, POSIX, BSD etc, for Linux. > > The glibc project retains a manual as a task-oriented guide which > can be read by developers to learn how to do certain tasks, but does > not contain API references (those are delegated to the linux man pages > project). We incrementally remove the API references in the glibc manual, > and convert them one-by-one into task-oriented documentation about how to > use that API well. > > I'm trying to think of a beautiful future. If you think this future > is ugly, please tell me so, and suggest something else :-) Well I'm glad you had an enjoyable Friday, and I hope you had a good weekend. And, as always, I appreciate your enthusiastic vision. Your future is not ugly, and I suppose all that you propose is technically possible. However, aside from the political discussions to resolve within the glibc project (and I am sympathetic to Joseph's perspective), this beautiful future rests on some shaky foundations. Here's my summary of some things that I think we agree on: * In many (but not all) areas, Linux man-pages does a better job of documenting glibc APIs than the glibc manual. * The glibc manual suffered from a long period of neglect. Things have gotten a little better in recent times, but (as Florian notes) there is still much to do. And there's not enough people working on addressing that, in part for reasons you described in another thread, and to which I added my perspectives. * Activity on Linux man-pages has been much higher. [1] These are the shaky foundations that I see: 1. What would change so that "the downstream C library implementations are all incentivized to contribute to the existing linux man pages"? You yourself note the reluctance of many developers to be involved in the documentation task. Reading your description above, I don't really see why the contribution activity would change. 2. Much of the difference between the activity levels on the glibc manual and Linux man-pages is down to a single factor: me [2]. As I've written various replies into the these discussions, I realize just how much I'm a bit of a unicorn: I'm a programmer who also really likes documenting things. And the question then is: what would happen to your beautiful future if I was not present? I have no immediate plans to step away, but nor will I be working on man-pages forever. And in any case, my activity level can be wildly variable depending on my other commitments and my available energy. Furthermore, while I think I've been moderately successful in raising the visibility of Linux man-pages since I took over as maintainer, there are areas where I've been notably unsuccessful: I've not been so successful at enlisting reviewers, so that too often I remain the reviewer of last resort; and after 15 years, there is so far no obvious contributor who might (want to) take over as maintainer one day. Really, both points 1 and 2 are about incentivization, and, lacking a population of unicorns, I think the fundamental problems aren't going to go away until companies/organizations pay people to work on the documentation. And I'm not sanguine about that prospect. With best regards., Michael [1] But a caveat also. It has been highly variable over the 15+ years that I have been maintainer, ranging from nearly 3000 commits in a calendar year (2014) to as low as 300 (2011), dependent largely on my energy and available time. Further caveat: the majority of the commits in any given release are by me; I think in all of the releases I made (~180 since 2004), only once was I ever not the majority patch contributor, and usually it has not even been close. [2] I don't want to overstate my contribution however. In 2004, I did inherit a solid foundation from my predecessor, Andries Brouwer. And I think there are also factors that play into the difference, including the CLA and also the visibility of the glibc manual and the usability of "info" as an interface. -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
