Re: The goal of the Linux man-pages project

[DJ Delorie <dj@redhat.com>]

What follows is my opinion.  You are free to have a different opinion,
but please don't tell me my opinion is wrong ;-)

Alejandro Colomar <alx@kernel.org> writes:
> It's the Linux Programmer's Manual, and its purpose is that
> programmers on a Linux system are able to write correct programs.

I think I disagree with the scope of "write correct programs" here.
"Write programs that use the APIs in a way that won't break" is not the
same as "write programs that use best practices", but "correct" covers
both.

> The purpose of this documentation is not, and was never supposed to be,
> a technical specification of the implementation.

In the past, that's exactly what man pages were.  You'd get a box of
printed manuals, one or more per section, with one or more pages per
program/file/function being described, and that was the gold standard
reference for the system the books came with.  Heck, even "man man" says
it's for the "system reference manuals".

I think that, in so far as the the developer wants to use our APIs, the
man pages must document what "is" and the information the developer
needs to use the APIs.  Note that I don't say "correctly" because that's
too vague - we should cover the correct way to *call* a function, but
not the correct way to *use* a function - if the programmer wants to
abuse the function for their own purpose, so be it.

If the man pages say what a function does, and what its parameters are,
and what it returns, that is unbiased factual documentation which the
programmer can use as they wish.

Where the man pages go beyond this, we call that "examples", "caveats",
and "best practices" and we have to be careful to disclose that they're
just recommendations.  It is not our place to tell the developer how to
write *their* code, beyond interfacing to our APIs.

I think the man pages need to, where appropriate, document the STANDARD
way of doing things, not what the author thinks might be better, or what
has been historically popular.  In the case of string.h vs memory.h, we
should take guidance from the current relevant published standards,
because future standards will assume that also.  If current standards
conflict with older standards, we could document that (perhaps in a
CAVEATS or HISTORY section).  We should NOT try to anticipate future
standards in the man pages, or suggest "best practices" that rely on
future standards.

> A programmer should be able to write correct code.

We need to leave the definition of "correct" up to the programmer,
outside of "legal API use".  Their code needs to do what they want, not
what we want, so long as the programmer sticks to the standards for our
APIs.

> A piece of documentation that describes an API in detail --as if it were
> reverse-engineering it from its binary code-- but doesn't tell me how
> to use it correctly is useless.

Again with "correct".  We need to document how to use it "according to
what the standards allow and what the function needs and does", and
possibly provide examples and caveats, but avoid trying to say "and you
should use it for these purposes."

> Okay, we have an algorithm.  I'm sure you can implement strncpy(3) from
> that description.  But what is it useful for?  Why would I want to call
> it?

Who cares?  We're not the developers, let them use the function if the
algorithm fits their needs.  We document printf() but don't tell the
developer what data they should print, just *how* to print it.  Same
here.  Tell the developer what the function does, but leave *why* to use
it up to them.

If you want to add a HISTORY section that explains the original purpose
of the function, go ahead.  But that has nothing to do with current
"correct" usage.

> How do I even call it?

That's the API that we need to document.  HOW is relevent here, WHY is
not.

> How am I supposed to write programs in a Linux system?

I think what you want is a programmer's guide.  While that may be
something to include in The Linux Documentation Project, it's outside
the scope of the man pages.  Even the TLDP FAQ says it provide "Guides,
HOWTOs, man pages, and FAQs", which implies that man pages are neither
guides nor HOWTOs.

Do I think we need more documentation to help people write better
software?  Yes!  Do I think the man pages are the right place for that?
No.

> Are there any systems without <memory.h>?

Irrelevant.  If the standard says those functions are in <string.h>,
that's what we should document in the pages for those functions.