groff
[Top][All Lists]
Advanced

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

[Groff] Effective manpages, a couple of thoughts


From: Larry Kollar
Subject: [Groff] Effective manpages, a couple of thoughts
Date: Fri, 7 May 2004 15:03:37 -0400

I thought I'd toss these ideas out for discussion before
dropping them into the next draft of my paper.


The "short and complete" requirement has a heavy bias
towards "complete," it seems. :-) That was the most heated
discussion I remember seeing on the groff list... but the
slings and arrows mean that people actually care how this
paper turns out. Pete Phillips's comment "keep it as short
as possible, but as long as necessary," was nothing less
than inspired and that became the new heading for the
section in question (which has been heavily redone, never
fear).

I've spent the last couple of days pondering what seems
like irreconcilable differences (at least for complex
software), looking for a way through that would work
equally well for both newcomers and experienced users.
Maybe I've hit upon something:

What do you think about the idea of having *both* a
long and a short manpage for a complex subject, where 
each references the other? In other words, one is
short, the other is complete. :-) My thoughts are
that someone new to the program (or *nix in general)
could use the short version to find the basic info
needed, and experienced users could access the long 
(default) version to get the entire scoop.


On a different part of the same topic, how many of
you who write manpages give much (if any) thought to  
making the NAME part of the manpage friendly to
makewhatis? Do you consider that important? Is it
worth discussing?

    Larry



reply via email to

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