man page terseness
I think this was also discussed a bit at the 2007-09-06 (or thereabouts)
BUUG meeting. Though it may be more true historically than so much
presently, I rather like to at least occasionally quote:
"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
This is still rather to quite true today with Unix(/Linux/BSD) man
pages. Most notably, they still tend to:
* describe things as they are and are implemented, rather than as they
should be. Notably, BUGS is a standard section for Unix man pages -
though some flavors may retitle that for marketing/political reasons -
e.g. instead titling that section NOTES, so as not to show "BUGS"
throughout the manual pages documentation. Man pages tend to be much
heavier on reality than hype ... this is probably at least due in
part to them tending to have a rather to quite technically demanding
audience - and hype just won't do well for the context in which
they're used and depended upon.
* be "complete and concise" - with emphasis on concise where those
objectives conflict - i.e. terse. Another way I might describe it,
from another context: "sufficient but necessary" - tends to include
precisely, but only, what's required.
Over time, however, the tendencies have changed a bit. "Back in the
day", UNIX man pages generally meant utilizing dead trees to print the
documentation - either in printed volumes for convenient and relatively
fast reference, or having them slowly and loudly bang out on a Teletype
ASR-33, or some other hardcopy terminal or printer ... because it was
much faster to read/skim them off-line, ... than wade through them on a
300 baud "glass TTY" ... if one was so lucky as to have a CRT terminal,
rather than a hardcopy terminal ... so being terse and concise was an
especially good thing.
But nowadays ... so, ... when's the last time your Unix flavor came with
printed man pages? What, ... perhaps about a decade or so ago? ... or
had they already changed to a not shipped with it but you could order
the bound volumes - for a price of course - by then? (probably depends
upon precise flavor and time). Anyway, today Unix manual pages rarely
(if ever?) ship in printed form with one's Unix flavor. Systems are
physically much smaller, more powerful, much greater storage capacity,
and much more numerous. Graphic capabilities - including in softcopy
display, are much more advanced and faster than in times past. The
volume of what's included in the operating system has gone up
tremendously, and that, at least in part, has accounted for much larger
volumes of the man page documentation. Also, however, as printing man
pages is much less common, and reviewing their text on-line is much
faster and more convenient, there's less criticality placed upon being
concise and terse - so that's caused the volume and size of man pages to
tend to increase. E.g. in times past, it was exceedingly rare for a
Unix man page to include example(s) ... such is no longer so rare.
In any case, however, Unix man pages still hang onto much of their terse
and concise tradition - and to a large extent that is quite good. Most
notably, people's time is a precious commodity, so better to try to be
concise/terse and not waste it. There are also lots of other places
that can include more detailed documentation/tutorials, etc. E.g.
Linux tends to have /usr/share/doc, and depending on Unix flavor, there
may be other collections/repositories of documentation - in many cases
available, or also available, via the Internet (Web, etc.).
And just for some comparison points:
sh(1) Seventh Edition, January, 1979 - 6 pages
bash(1) (from the flavor/version I'm using at the moment) - 4527 lines -
or roughly 69 pages.
Seventh Edition, January, 1979, Volume 1 - about a 1" stack of 8.5x11"
pages printed double sided - perhaps somewhere between 150 and 400 pages.
manual volume 1 of flavor at my fintertips - roughly 11,891 pages:
$ cat man1count
#!/bin/sh
cd /usr/share/man/man1 &&
echo \
$(
for tmp in *
do
set -- $(echo "$tmp" |
sed -e 's/\.gz$//;s/\.\([^\.][^\.]*\)$/ \1/')
2>>/dev/null man "$2" "$1"
done |
wc -l |
sed -e 's/[ ]*//'
)/66 |
bc -l
./man1count
11890.06060606060606060606
$
http://www.rawbw.com/~mp/unix/sh/