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
