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

[Meg McRoberts]

--- Clarke Echols <address@hidden> wrote:
> 
> 
> Pete Phillips wrote:
> 
> > >>>>> "Larry" == Larry Kollar <address@hidden> writes:
> > 
> >     Larry> What do you think about the idea of having *both* a long and
> >     Larry> a short manpage for a complex subject, where each references
> >     Larry> the other? In other words, one is short, the other is
> >     Larry> complete. :-)
> > 
> > Well, from my point of view, it wouldn't break my current working
> > practice, so seems reasonable. In principle I think it's a good idea,
> > but ......
> 
> 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.

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. Cross-refs
from the man page to other material help but don't solve the problem.

Clarke's recommendation to keep the short, simple stuff up front and then
put more details later in the page matches my previous recommendation --
have a very short "Description" section (usually just a couple sentences),
followed by a list of the options/arguments/fields/members/whatever, then
do a "Usage" section that has more of the gory details.

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

There are other wrinkles here.  For example, if you have a fairly small
structure that is only used by one function (or function pair -- one function
to allocate and one function to free, fro example).  The purist in me still
thinks that structure should be documented on its own page, but practically,
it is much easier f that structure is just documented on the man page for the
function(s) that call it.

But these decisions may need to be revisited over time.  For example, at one
time, it made sense to have all the signals documented on the signal(2) page.
Then sigaction(2) came along and had to reference signal(2) for the list of
signals.  Someone finally got the idea to create signal(5/7) (the miscellaneous
section) to list the signals but it was an awkward situation for a long time.
I just checked the page on my Mandrake system and discovered that signal(2)
doesn't include signal(7) in the "See also" list either.

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?

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.

meg

meg


        
                
__________________________________
Do you Yahoo!?
Win a $20,000 Career Makeover at Yahoo! HotJobs  
http://hotjobs.sweepstakes.yahoo.com/careermakeover