Re: [Groff] Draft paper: "Writing Effective Manual Pages"

[Tadziu Hoffmann]

> Most seem to agree that the bash manpage is too big

I for one would like to disagree (and somewhat reduce that "most").

The manpages are a *reference* manual, and *have* to include
all that's relevant.  Complex and intricate programs with
many functions and options need longer manual pages.  Period.
If the bash manual page were made any shorter by leaving
something out, it may become completely useless, because the
next time I accessed the reference, perhaps exactly that bit
of information was what I needed/wanted to know.  I would
hate to see a reference split up into "manual for dummies"
and "manual for experts".

The bash manual page *is* concise, as you would expect for
a reference.  It is neither a tutorial nor a philosophical
treatise on the whys and wherefores.  (This is currently
the domain of the info pages -- not ruling out that these
cannot be just as well be presented in manpage format.
Question:  What's the best way to read info pages?
Answer: info foo | less.  The search capabilities of less
are so useful that you can easily do without all that
navigational gimmick.)