Yeah, I'm
less angry at GNU now--I didn't search as hard, but when I found
out 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is still
actively-ish maintained) then I figured it wasn't something classical that
GNU dropped, just never imported. I feel like it existed on SunOS and
Solaris but I might be wrong about that? Was it really FreeBSD that
introduced it?
I don't think SunOS had it. The SunOS man pages were pretty terse, the
powers that be wanted just the facts. I remember get beat up for putting
examples in some of the man pages I wrote, they got taken out "because
examples are for user guides, man pages are not user guides, they are a
reference guide" or something like that.
I like examples in man pages, I think it jump starts you into using the
program more easily but maybe that's just me.
--
---
Larry McVoy Retired to fishing
http://www.mcvoy.com/lm/boat
I'm glad I'm not the only one, do I find the dearth of examples on many
reference manuals to be quite annoying. The only compelling (to me) reason I've ever
heard for flat out avoiding examples is to not imply best practices. For instance, in my
own work, there are times I purposefully have to not provide use-case examples of some
generic bit I put together because then I find it gets used very narrowly, as if the
example given is "how it should be used" rather than "a way it can be
used". Granted, that is a product of perception, not intention, so outright avoiding
guidance altogether or not, you're always going to have people who read something and
accept that as lore rather than just a helpful suggestion or narrow demonstration.
It's kinda like providing a reference implementation of some general interface or
service. If it works well and is general, folks are just going to use that reference
implementation rather than customizing their own logic to drive the interface, defeating
the purpose of trying to standardize an interface instead of just providing a distinct
product. Kinda like X these days, how many *new* X servers or clients have popped up
lately? Is everything X.org now? I don't know enough to speculate on that but might
serve as a good example.
Another way I think about that caveat is, say one is providing an example of fseek. A
narrow example of seeking to the end of a file would be an effective example, a perfect
use-case for fseek. However, presenting instead a bulkier example that demonstrates
determining filesize *using* the fact you can fseek to the end and then ftell the
position, while also demonstrating use of fseek perfectly well, might embed itself in
someone's mind as suggesting *the* way to do this sort of thing in C. Granted,
again, that's up to user perception, but those are the kinds of scenarios that do
give me pause when drafting examples for documentation: The concern that someone will take
an example as an absolute in every angle that it touches.
I think in a full UNIX manual, constituting both volumes (or whatever other permutations
of manpages and doc papers), it does make a bit more sense to keep examples terse because
for many materials needing detail, one could simply cite the paper that is also considered
a part of that standard documentation package. Sadly with the fragmentary nature of
documentation these days, that sort of packaged manual doesn't really exist anymore,
and all of what would have gone into that arrangement of documents is out leading multiple
lives as info, HTML pages, PDFs, etc probably from TeX sources. /usr(/share)/doc is a
thing of the past in its old way of being. I guess these days what with the internet and
all, it's less important for each and every scrap of information being succinctly
accessible by a common mechanism on the system itself...but hoo boy would it be nice...I
guess that's what they wanted info to be but...yeah that needs no further comment
from me.
- Matt G.
