[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[segaloco via TUHS <tuhs@tuhs.org>]

> > 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.