[sf-lug] Manpages are ...

[Michael Paoli]

Quoting Rick Moen <rick at linuxmafia.com>:

> Manpages are "quick reference" docs, refreshers on fine details intended
> for the use of someone who already basically knows that topic.

Though perhaps changed slightly/somewhat* over the years, on the
topic of the manual pages, I think this is still (at least mostly)
quite fitting and bears repeating:
"Within the area it surveys, this volume attempts to be timely,
complete and concise. Where the latter two objectives conflict, the
obvious is often left unsaid in favor of brevity.  It is intended that
each program be described as it is, not as it should be."
- UNIX PROGRAMMER'S MANUAL, Seventh Edition, January, 1979, Volume 1,
INTRODUCTION TO VOLUME 1

*examples are significantly more common in man pages these days; such
was quite rare once-upon-a-time (e.g. it used to be examples were
typically only included if rather to quite absolutely necessary to
make a key point that would be very difficult to otherwise infer from
the documentation).  Also, with much faster and capable softcopy
displays, as opposed to hardcopy terminals and printed manual pages,
and also much cheaper storage costs and much faster more capable
systems, providing much more information without the banging of
teletype output and printing, and having it much more quickly
searchable and viewable, there is a general tendency to no longer
limit manual pages to the bare minimums sufficient to cover the
materials.  They do, however, still generally avoid being excessively
verbose and providing excessive examples and such.  They continue to
(with negligible exception**) not be "tutorials".

**e.g. perltoot(1) could well be considered such an exception