Re: CVS commit: src/lib/libc/stdio

[Mindaugas Rasiukevicius <rmind%netbsd.org@localhost>]

Jukka Ruohonen <jruohonen%iki.fi@localhost> wrote:
> On Wed, May 05, 2010 at 12:58:13AM +0700, Robert Elz wrote:
> >   | As something like gets() has been standardized for ages, it makes
> >   | sense to explicitly note that this may no longer be true (with
> >   | respect to POSIX).
> > 
> > That's where I disagree, it is just bloat - once it stops being a
> > standardised function, just stop calling it one.   If the doc notes that
> > fgets() is POSIX, and says nothing about gets(), the implication is quite
> > clear, isn't it?
> 
> I think the term "bloat" hardly ever applies to manual pages. If anything,
> they are often too terse. A paragraph or two about history or standards
> never hurts anyone. Two additional things: <...>

I think it does apply.  Manual pages are something one works with, like a
tool.  Ability to easily and quickly find the information you need is an
important factor.  If you will write fairy-tales, that wont be convenient.

> > That history will be in the CVS logs.   That's enough for maintainers.
> > For others reading the man page, this is all irrelevant (it would almost
> 
> I think the history is relevant or at least interesting; one of the
> intriguing things about UNIX, really.

History is indeed important, however it belongs to books, articles, etc.
Other part of history belongs to version control logs, as Robert already
mentioned.  If I will want to figure out why and by whom some function was
invented, how it looked originally, why it diverged, etc - CVS logs will
likely answer that better, than a manual page.

-- 
Mindaugas