The GNU C Library Manual - Authoritative or not?

[Michael Kerrisk]

[CC += linux-man@]
[Context: https://lwn.net/ml/libc-alpha/875300cf-92ca-c115-c42d-19dda5de5a4a@redhat.com/]

On Fri, May 22, 2020 at 3:07 PM Carlos O'Donell via Libc-alpha
<libc-alpha@sourceware.org> wrote:
>
> On 5/21/20 8:22 PM, Martin Sebor wrote:
> > On 5/21/20 4:11 PM, Carlos O'Donell wrote:
> >> On 5/21/20 1:46 PM, Martin Sebor wrote:

[...]

> > It would be a considerable
> > effort to bring the manual up to par with the Linux man pages.  I see
> > little point in investing it into duplicating what already exists
> > elsewhere and what according to documentation.html many of you are
> > already contributing to.  My suggestion instead is to declare
> > the Linux man pages the reference and treat the manual as a user
> > guide.

So, as an aside, I think the Linux man-pages are rather better than
the glibc manual in many areas, but there some areas where where the
reverse is true. And lately I see patches to the glibc manual from
Florian, and sometimes I realize: "oh that's not covered in Linux
man-pages". So, notwithstanding what the glibc developers may thing
of the idea, from my perspective the notion of declaring man-pages as
the [authoritative] reference would not be without problems.

> I appreciate your suggestion.
>
> I agree it would be a waste of time to duplicate what already exists.
>
> The glibc manual should be a guide and it should contain complete and
> authoritative information about the APIs it implements. This does
> not include version-by-version changes, bugs, raw syscalls, etc.
>
> I think having the linux man pages as a non-authoritative reference
> is very good, and I contribute to the linux man pages.
>
> I think having WG14 work on ISO C is also good, so I contribute where
> I can to SC22 in Canada for that reason.
>
> That makes 4 documents covering the same APIs!
>
> * ISO C (the standard)
> * POSIX (the extended standard)
> * glibc manual (the authoritative manual for glibc's implementation)
> * Linux man pages (detailed syscall and API reference documentation)
>
> FWIW they all serve different purposes.
>
> The linux man pages are *great* they even document version to version
> differences and if you're interested in targeting specific versions of
> glibc you can use them accurately to write code that does exactly
> what you would expect. That's awesome! Our manual does not have that as
> a goal.
>
> >> This is not a duplication of effort IMO. The manual and the linux man
> >> pages solve different needs. The manual is task-oriented, covering
> >> sections of the standard APIs and how they could and should be used
> >> together,

And yes, in places this is where the glbc manual does really excel.

> >> while the the linux man pages are API references only
> >> (in isolation to the larger set of APIs).

Broadly true, although in places, Linux man-pages tries also to draw
bigger pictures (e.g., various overview pages in Section 7).

[...]

> > A report of the warning above is what prompted my question.  I had
> > checked the C and in some cases also POSIX standard as well as
> > the Glibc manual when adding the attribute.  C doesn't have this
> > extension, Glibc doesn't document it, and I missed it in POSIX (or
> > more likely didn't think to look there in this case).  What I was
> > looking for with the question is an acknowledgment of what I had
> > suspected, namely that the Linux pages can be trusted to accurately
> > document this and other Glibc extensions.
>
> The linux man pages can *absolutely* be trusted to document every
> change glibc makes, but that doesn't make them authoritative, it makes
> them detailed. As a developer I love the detail in `man mbstowcs`.

I commented on this already. I wish the above were true, but Linux
man-pages does not manage to track all of the changes.

[...]

> > But from a simple usability point of view, it's unhelpful to tell
> > people to consider the union of the Glibc manual and all external
> > documentation (or some subset of it).  Not just because it's
> > impractical to read everything, but also because not everything
> > is correct or up to date.  How are they/we supposed to resolve conflicts?
>
> We resolve conflicts by writing things in the manual to cover such cases,
> and we do so tactically to resolve problems as they arise.
>
> Over the years the project has had a significant lack of engagement with
> writing good documentation,

Yes, the manual seems to have started very well, but then the wheels
came off for many years. (Surprisingly, during that time I would
occasionally get a piece of very helpful input for man-pages from
Ulrich Drepper!)

> and I can understand that. It's hard to
> write clear and unambiguous English sentences to describe an interface
> and how it dovetails into the rest of the APIs.

Yes, best to leave that task to the Germans. (Sorry; I could not
resist the hat tip to Florian.)

> Such writing is not as
> much fun as writing code.

Yes, I never really understood that one. It's only by explaining (my)
code very clearly at least to myself, but probably to others, that I
can feel like it is/I have written good code. Writing good human
language expression is just as much an interesting challenge as
writing good programming language expression.

> We really need to engage with technical writers
> and involve a broader set of industry skills in our projects.

I want to add a note of caution here. It's great to have technical
writers (and like good developers companies should be paying them),
but they can't do the job on their own. A lot of developer input is
still required.

Thanks,

Michael