Re: [groff] mom manpage

[Doug McIlroy]

> Bash is a complex program, and the length of the manpage is
> entirely adequate.

It's adequate in the sense of being quite complete and accurate. It's
also verbose. The introductory paragraph is laudably crisp. But right
after that comes

-c        If the -c option is present, then commands are read from  the
           first non-option argument command_string.  If there are argu‐
           ments after the command_string,  they  are  assigned  to  the
           positional parameters, starting with $0.

Like much of the page this can be said in half the space:

-c         The first non-option argument is the script. Further arguments
            are assigned to the script's positional parameters $0, $1, ...

One may fairly object to the use of the undefined term "script". However,
the word already occurs 36 other times in the document. It should be defined
up front, perhaps by an opening sentence like this:

         Bash executes a "script" of commands, which is read from standard
         input by default.

The weasel-word "quite" in my opening sentence is deliberate. Verbosity
fosters errors: more text presents a larger cross-section to random
mistakes and challenges a proofreader's span of attention.

The quoted paragraph is a case in point. It reveals that the Synopsis

         bash [options] |[command_string | file]

omits the special syntax for positional parameters. I think a proofreader
of the shorter version would be able to pay more attention to the content,
and be more likely to spot the error. In my own case, the effort of
shortening forced a focus on the content, and prompted me to check the
Synopsis, thus uncovering the trouble.

Turning attention to statistics: given that one discrepancy exists within
the first 25 lines of the documentg, how many will there be in the whole
5000+ lines?

-------------------------------------------------------------

Getting back to the original subject, this thread led me to peek at
a few pages of Mom's 35,000-line html documention. I noticed a number
of proofreading oversights and stylistic inconsistencies that probably
would have been excised long ago had the document comprised only those
pages. Maintenance of the whole, though, is a daunting task.

At the same time, I was impressed by the thorough cross-linking in
Mom's documentation. It was easy to find explanatory information,
though I would quibble about how often reference inquiries could only
be answered by reading tutorial explanations. A major case in point:
the quick macro reference gives only macro names. You must follow a link
to be reminded of the arguments.

Before making this little foray into Mom, I had been put off by its
LONG_CAPITALIZED_MARKUP, which would quite dominate much of the fiddly
stuff I write: mathematics and man pages. This visit, though, led me to
realize that Mom gets closer than other general macro packages to one
of Joe Ossanna's original dreams, mechanization of style sheets to such
a degree that you can make major changes to style after the fact.

I'd be interested in hearing about experience with, say, taking a Mom
document written with one journal in mind and rendering it in the style
of another. (Neat as this would be, though, it probably wouldn't help
with submission, because journals are prone to insist on Word or Tex.)

Doug