groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] Effective manpages, a couple of thoughts


From: Larry Kollar
Subject: Re: [Groff] Effective manpages, a couple of thoughts
Date: Mon, 10 May 2004 22:53:38 -0400

Clarke Echols:
When I was designing HP-UX sys-admin online help, I kept the short,
simple stuff up front, and the deep, complex stuff later in the file,
not unlike a well-written manpage. Cover the simple stuff like options
and flags, then keep the detailed stuff for later, but don't split it
into a short/long version or I'm stuck with trying to remember which
has what in it.

Good point about covering the simple stuff first. I'm not sure I agree
that separate short/long manpages would be that much of a problem.

Meg McRoberts:
Over the years, I've seen many attempts to supplement short manpages with some other form of document that would have all the gory details and they've never been successful. In general, I find that people will look in the man
page and, if something isn't there, assume it isn't documented.

That's interesting. I think that the traditional troff/macro manpages are a
counter-example though... all of them defer serious commentary to either
CSTR reprints or printed manuals. You might not be able to find them,
but you know it was documented... somewhere. :-(

Having a "short" and "long" manual page creates a lot of practical maintenance problems -- it sounds like a good idea but can be non-trivial to implement. There are some bits that are obviously "basic" and others that are obviously
"advanced" but a lot that fall in the middle and could go either way

I don't know about non-trivial. You can source both pages out of a single
file, using nroff to process it. Something like this:

.cc @
@ec |
@nf
@ie rSHORT .TH foo_short 1
@el .TH foo 1
.SH Name
foo \- the canonical example
.SH Synopsis
.B foo
.RB [ -b ]
.RB [ -a ]
.RB [ -r ]
@if !rSHORT |{|
.RB [ -q ]
.RB [ -x ]
.RB [ -z ]
@|}
.RI [ file ...]
.SH Description
The
.B foo
program reads a file and processes it.
@ie rSHORT |{|
This document is a quick reference,
describing only basic features; see
.IR foo (1)
for a complete description.
.|}
@el |{|
For a quick reference to
.BR foo ,
see
.IR foo_short (1).
@|}
.P
And so it goes...

Use "nroff -Tlatin1 foo.n | sed -e '/^$/d'" to generate the standard manpage, and "nroff -Tlatin1 -rSHORT=1 foo.n | sed -e '/^$/d'" to make the short one. Drive it out of a Makefile. Probably the harder part is deciding what's basic, like you said, but even that might change over time. Start *somewhere* with
an educated guess, and listen to feedback.

As I hinted above, my thought was that the long manpage would be the
default, but the short one is there for someone trying to remember the
simple stuff & not having time/patience to wander through a long page.

BTW, using "less" to search around is nevertheless a good idea... perhaps
we should lobby to have that suggestion added to the man(1) manpage?

A basic man page is about the easiest document to write and also easy for the user to access. Alas, creating, maintaining, and architecting a good set of man pages is a lot of work and requires a whole lot of thinking on someones
part.  Ironic, isn't it?

I'm not sure basic manpages are that easy to write... look at all the discussion this has generated. Then again, like any other kind of writing, it's easy to write but more difficult to write *well*. :-) Thus, the "effective" part.

Hence the importance of this "Effective manpages" document. I think setting down some of the considerations for people who are new to manpage creation is extremely useful -- we don't need to make rules or even recommendations,
just put forth some things to think about.

Right... that's been my goal from the beginning. Guidelines, nothing more.
Useful guidelines, I hope, but certainly nobody's marching orders....

--
Larry Kollar     k  o  l  l  a  r  @  a  l  l  t  e  l  .  n  e  t
Unix Text Processing: "UTP Revival"
http://home.alltel.net/kollar/utp/



reply via email to

[Prev in Thread] Current Thread [Next in Thread]