Re: man-intro

[Peter Schaffter]

On Sun, May 23, 2021, Oliver Corff wrote:
> in a follow-up to my last message I just want to give one
> real-world example of a very terse manpage, "for the initiated
> reader only."
> 
> Take refer(1).
<snip>
> Terseness is nice, but in the case presented here the first paragraph of
> DESCRIPTION in the refer(1) manpage is logically true, though not truly
> helpful.

In support of Oliver's feelings on the subject, I cite from the mom
documentation, written years ago:

 "Refer has been around for a long time.  It's powerful and has many,
  many features.  Unfortunately, the manpage (man refer), while
  complete and accurate, is dense and not a good introduction.  (It's
  a classic manpage Catch-22: the manpage is useful only after you
  know how to use the program.)"

(Pedants: I use Catch-22 in its popular meaning, not the strict
Hellerian definition.)

> Sometimes a minimal degree of verbosity makes everything clearer.

Hear, hear.  I had a German prof at UofT years ago who was fond
of saying: Never use one word where two will do.  Ironic, given the
source, but he was talking about English style, not German.

I confessed to Branden off list recently that the origins of the mom
macro set are to be found in my intense frustration with the terse,
nearly opaque documentation of all things *roff.  (Exception made
for cstr54, which somehow balances conciseness with readability.)
My feeling was that if I could translate groff's machine-code
documentation to something humanly readable, it would attract users.
That morphed into "Why not write a complete user interface for
groff and document it separately, sparing users from having to read
*roff documentation at all?"  Years later, I realise I bit off far
more than I expected to chew, but the idea was sound.  Mom and her
documentation have drawn a lot of new groff users.

-- 
Peter Schaffter
https://www.schaffter.ca