[TUHS] man-page style

[Eric Allman <tuhs@eric.allman.name>]

[I sent this almost a week ago, but it never showed up, probably because
my From address didn't match my subscription address.  Apologies if this
is a dup.]

On 2018-11-19 07:35 , Clem Cole wrote:
> As I said, if man had been maintained as the primary >>manual<< style
> interface and /usr/doc/<PROG>/foo.ms <http://foo.ms> as the primary
> scheme (which >>IS<< what BSD did), then you don't fail the rule of
> least astonishment. 

On 2018-11-19 09:39 , Theodore Y. Ts'o wrote:
> I'm not convinced the original BSD man page for, say, "make" is really
> sufficient to learn how to use make effectively w/o the expanded,
> non-man page write up in BSD Unix's Programmers Supplementary
> Documents.  So I dare say the goal that the man page should be the
> primary manual was a bit of an aspiration goal as well.

The /usr/doc/<PROG>/... convention started at least as far back as 7th
Edition (and I think 6th as well).  There was no attempt to make the man
page for yacc or troff document everything you needed to know --- they
basically listed the command line arguments and gave you a pointer to
the real manual, which went into far more depth than would be feasible
in a man page, sometimes including things like tables and figures (using
tbl and fig, of course).

Speaking of troff, that was interesting documentation.  Ossanna's
documentation told you exactly what all of the commands did, but didn't
say why they did it.  Many of the features seemed absolutely crazy at
first.  I probably read that document 50 times when writing the -me
macros, every time having a light bulb go off in my head.  I finally
concluded that _everything_ was needed to do something useful, and you
could do pretty much _anything_ with the available tools (including
things like page balancing).  A master work of design, and blissfully
complete documentation (even if a bit obscure to the newbie).

eric