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

[Ted Harding]

Excellent comments, Larry! (Mind you, I would think that,
woudldn't I).

On 04-May-04 Larry Kollar wrote:
> One thing that everyone who has responded so far has said, with
> varying degrees of emphasis, is that my suggestion for a two-page
> limit is too tight. Most seem to agree that the bash manpage is too
> big, so we at least have a consensus between 3 and 57 pages.
> I still want to lean very close to the low end of that range, though.
> Let me provide a little background for my thoughts.

Interesting discussion of the role of short-term memory. Valid as
far as it goes, but it doesn't incorporate the factor that many
references to "man foo" are for the purpose of looking up something
specific (e.g. an option, or one of the commands that "foo" can
execute). Certainly applicable, though, when someone is looking
into "man foo" in order to find out what "foo" can do.

> However, the 20-second time limit means that unless you're
> familiar with the layout of a long manpage, you're going to get
> lost in a hurry. As an experiment, I started "man bash" in an
> xterm window and started skimming the headings. In 20 seconds,
> I got to "Shell Variables" -- the top of page 8 if you created a
> printed version. So perhaps 7 printed pages is a reasonable
> upper bound, and I wouldn't be a hypocrite because my rewrite
> of groff_ms.7 is seven pages + 1 paragraph long. :-)

I've done that too ... but I now (longer-term) remeber that
there is such a section so, once "man bash" has come up I'd
make sure "ignore case" is switched on in "less" and then

  /shell var

(have to press "n" once since the first instance isn't the
section) 


> The other thought is that so much of our console software has
> outgrown the mental limits of manpages that I describe above.
> The yardstick for manpages is "short and complete" because
> in the Elder Days manpages *could* be both short and complete.
> For example, the longest manpage in section 1 for Unix 3rd
> Edition was the complete reference for ed(1) and it runs about
> 5 printed pages (I'm guessing, since the source appears to have
> been partially compiled down to *roff requests but using back-
> spaces to generate underline/emphasis). The sh(1) manpage
> was a little shorter, maybe 4 pages. The others were significantly
> smaller; certainly none of them approach that 7-page limit.

Yes, this is where documentation of the program's functions
can outgrow the natural confines of a man page. I wouldn't
want to have to learn LaTeX solely from some "man latex"--you
need a book or several for that, which is the right place for
documentation on that scale.

I've considered this question more than once, and I reckon that
"man awk" is just about within man page limits. But this is
probably a consequence of the fact that "awk" is fundamentally
very simple in concept, powerful though it is. The complications
with "man awk" arise because of its different versions and
compatibility issues; but I think this could be usefully solved
with "man awk" which simply summarised the version differences,
with pointers to "man awk.old2, "man awk.posix", "man awk.gnu"
or whatever. However, I don;t really have a problem with "man awk"
as it stands.

"man troff" is an interesting case. The functionality is of a
similar order to TeX, yet the usage of requests and escape sequences
is sufficiently consistent across the board that it's feasible
to list the lot, with short definitions, on the lines of the
way command-line options are listed in a man page. Most people
(once used to troff) would use the man page either to remind
themselves of precise usage or to remind themselves (or find
out) what request/sequence to use for a particular purpose.
Once again, astute searching in "less" can find what you want
very quickly.

On the whole, though, I agree that "short but complete" is the
thing to aim for; and there certinaly is software which cannot
be described in such a way.

> But none of that makes manpages irrelevant. To put it bluntly,
> there is no other format out there that is both widespread and
> allows both console viewing and printing from the same file.
> Despite attempted marginalization by the FSF and others,
> people still type "man foo" first thing. Speaking as a technical
> writer, this is good; it means that I know what to provide.

Agreed!

> So despite its age, despite software growing beyond the
> comfort zone where its documentation *can* be both short
> and complete, despite attempts to supplant it, the venerable
> manpage remains both necessary and useful. Rather than
> evangelizing, as Alejandro suggested, my motive was to
> illuminate the limitations of the format and (I hope) illustrate
> some best practices for making the most of what it offers.
> (And "gracias" to Alejandro for the offer to translate!)
> 
> Perhaps the goal should become "short, and where possible,
> complete." Quick references, also known as cheat sheets, only
> become necessary once the full documentation gets too big
> to navigate quickly. Does anyone disagree we're at that point?

I don't disagree! Not with anything in the above.

Cheers,
Ted.


--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Fax-to-email: +44 (0)870 167 1972
Date: 04-May-04                                       Time: 17:04:59
------------------------------ XFMail ------------------------------