On Wed, 18 Oct 2006, Roland Illig wrote:
> the recent thread on the isspace(3) function motivated me to write an
> explanation about the topic, and I would like to include it in the
> ctype.3 man page, so that it looks like the appended one.

It looks good, but I haven't studied it closely.

> Now the questions are:
> - What target audience do we have for the man pages?
>   - C language lawyers (in that case it wouldn't be necessary)
>   - Casual C programmers (who may find the information useful)
>   - Beginners (to whom the information is essential)

I would say that the target audience is all of the above.  We should
provide accurate information for language lawyers, and helpful
information for beginners.

> - Do we want to provide such programmer-friendly documentation that 
> tries to prevent bugs, increasing the code quality?
> 
> - Or are the man pages just references, and we don't care much about 
> their quality?

Are you suggesting that (being a reference) implies (quality does not
matter)?  I don't think the one implies the other at all.

I think that the man pages are references, and that we should care
deeply about their quality.  I think that it's useful to provide some
tutorial material, much as you have done in this case, but that we
should stop short of making the man pages a "how to learn to be a
programmer" guide book.

--apb (Alan Barrett)