Re: The GNU C Library Manual - Authoritative or not?

[Florian Weimer <fweimer@redhat.com>]

* Michael Kerrisk:

> Each year I come into contact with quite a large number of developers
> (some few hundred each year) in many locations in my day job (or, at
> least what used to be my day job until COVID-19 landed), and I think
> *very* few of them are aware of the existence of the glibc manual.
> Most are aware of manual pages. (However, they mostly aren't aware
> that there is an project entity called "Linux man-pages"; rather, they
> just know that they get a pile of manual pages on their systems, and
> many of them consult those pages.)

Thanks for sharing your perspective.

> And then there is the "info" thing. As a complete document (i.e.,
> PDF), the glibc manual is quite a handsome document with a lot of good
> information, but not the thing one wants to reach for when facing a
> specific API problem. What is one then left with? "info". I think in
> all of the years that I have been around Linux, I cannot recall
> meeting anyone who had a kind word to say about this format/interface.
> People generally don't understand how to navigate in "info", and I
> think the whole idea of hyperlinking in a textual UI is one that
> doesn't work well from a usability perspective. https://xkcd.com/912/
> is funny for a reason.

Even for Emacs users, I suspect that many more are aware of “M-x man RET
RET” than those that are aware of “C-h S”, which jumps right to the
function documentation in the glibc manual.  I have not figured out how
this actually works in practice.  I suspect it uses the Texinfo function
index.  Unfortunately, quite a bit of useful information in the Texinfo
sources is not visible in rendered versions.

One could try to get something similar to “C-h S” into Visual Studio
Code and other IDEs.  But I'm not convinced this is a good use of
resources.  Even if I can remember the Emacs command, I usually need the
manual pages because I'm more interested in the system call
documentation.

> And on that last point, I circle back to an issue that I've banged on
> about before. The CLA. It's just a huge barrier to contribution (and,
> I remain convinced, A Bad Thing [TM], even if its motivation is well
> intentioned [6]). Just in the last day or two, there's someone doing
> what seems natural to so many in this (FOSS) world:
>
> https://lwn.net/ml/libc-alpha/20200523191809.19663-1-aurelien.aptel%40gmail.com/
>
> I presume this patch submitter has no idea of the existence of the
> CLA. Once that person learns of it, will they bother doing the
> paperwork, or will they just never bother submitting another patch? I
> know which way I would bet my money.

I still haven't given up hope entirely for relicensing the manual under
a license that is compatible with Debian's requirements, and also making
it easier to move code and documentation between the manual and the
implementation itself.  The current copyright assignment procedure means
that there is no legal or technical obstacle to relicensing, one has
simply to convince the single copyright owner.

Thanks,
Florian