[Top][All Lists]
[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/
- [Groff] Effective manpages, a couple of thoughts, Larry Kollar, 2004/05/07
- Re: [Groff] Effective manpages, a couple of thoughts, Mike Parson, 2004/05/07
- Re: [Groff] Effective manpages, a couple of thoughts, Pete Phillips, 2004/05/09
- Re: [Groff] Effective manpages, a couple of thoughts, Clarke Echols, 2004/05/09
- Re: [Groff] Effective manpages, a couple of thoughts, Meg McRoberts, 2004/05/09
- Re: [Groff] Effective manpages, a couple of thoughts,
Larry Kollar <=
- Re: [Groff] Effective manpages, a couple of thoughts, Meg McRoberts, 2004/05/11
- Re: [Groff] Effective manpages, a couple of thoughts, Clarke Echols, 2004/05/11
- Re: [Groff] Effective manpages, a couple of thoughts, Werner LEMBERG, 2004/05/12
Re: [Groff] Effective manpages, a couple of thoughts, Jorgen Grahn, 2004/05/11