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

[Clarke Echols]

I have been sitting on the sidelines and not reading the groff emails,
but I probably should jump in here a bit.

I wrote manpages for HP for several years (HP-UX 5.0, and 7.0 through
9.0) in 1985 and 1989 through 1992.  I have learned several things
that are important.  Consistent use of fonts and case (CP in the header
(in Roman font), cp in the synopsis (syntax) section (in bold), and Cp
in the description when it appeared at the start of a sentence (in italics)
and cp (again in italics) in the body of sentences is ***NOT*** the
right way to do it.  Thus in 1989, I converted all literals to Courier,
headings had same uppercase/lowercase as actual usage, and arguments
or variables were in italics.

Keep it terse, but also complete.  Nothing annoys me more than a manpage
that does not give me what I need to know to use it effectively (such
as awk(1), but I understand why it has to be that way.  There is no
way to put all of the troff/nroff/groff requests in a manpage, but it
would be immensely useful if it were *somewhere* in the /usr/man/man*
tree!

One of the reasons I left HP five years ago was because the manpage
documenters' manager refused to produce the manpages on customer machines
in HTML for access by web browsers I was using for online help.  They
had the software to do it (source files had been moved to SGML with
a translator back to troff) and I wrote the shell script that built the
printed and online manuals -- one page added to that program would have
solved the problem but they didn't want me to do it because my script
was now on their turf.  I probably shouldn't go further on this because
it's one of my hot-button topics of what's wrong with Corporate America
and the bozos that occupy positions of "responsibility" therein...

Get very familiar with and *USE* man macros.  Use .TP (the troff
counterpart to <ul> <dl> and <ol> in HTML).  I much prefer .BI,
.IR, etc. over \f3 \f2, etc., and remember that \fR puts you back
into Times Roman regardless of what fonts are specified for .fp 1,
.fp 2, and .fp 3 in the macro package, so don't use \fB, \fI, \fR
in manual pages.

EXAMPLES!!!  Put some very good examples in it.  And make the
SYNOPSIS useful.  When I rewrote the cp(1) manual page, I didn't
compact it the way AT&T did in their cp/mv/ln combined manpage
(a *really* bad idea! -- it was so full of holes it was pathetic).
I showed in the synopsis how to:

  - copy file to a file
  - copy files to a directory
  - copy directory trees to a directory

That's much easier than explaining a complex bunch of options and
flags and it allows me as a user to immediately fit the syntax
to my needs with little confusion.  To access the page:

http://docs.hp.com/hpux/onlinedocs/B2355-90128/B2355-90128.html

Click on Section One, then "c" then "cp(1)" to get the page.

Unfortunately, I know of no way to access the original troff coding
online so you can't see how I used macros.  Some time spent in these
pages should give you some good ideas, though.

Clarke



Meg McRoberts wrote:
> 
> --- Jon Snader <address@hidden> wrote:
> 
> > I reluctantly must agree with this.  As annoying as long man
> > pages are, they're preferable to omitting vital information or,
> > worse yet, the odious Perl practice of making every single
> > function a separate man page.
> >
> > We may be overworking this issue.  The point of Larry's paper is
> > to lay out some guidelines for making man pages useful, not to
> > serve as draft legislation.  If we all keep our man pages as
> > short as possible while covering the required material, we will,
> > in general, limit most man pages to a MANagable 8-) length.  Some
> > cases, such as bash, just have to be exceptions.
> >
> > As others have said, the info system is a non-starter for me.
> 
> I think a distillation of this discussion would be a very interesting
> addition to this paper.  It's taken the rest of us a long time and a
> lot of man pages to understand the issues, and this information could
> be very helpful to people who are just starting to write man pages.
> 
> I'm actually facing the need for such a little paper and thought about
> starting one.  The company where I work has been a Windows shop with a
> few Linux products.  The Linux work is growing and *someone* started
> doing man pages for the Linux products.  Other writers want to learn
> how to do man pages.  To do this, they need to learn the macro set and
> all but they also need to learn how to structure the information for a
> man page.  I think we all agree that the "ideal" man page is quite short,
> and thinking of brevity is a good idea even when the subject matter requires
> that the man page be long.
> 
> meg
> 
> 
> 
> __________________________________
> Do you Yahoo!?
> Win a $20,000 Career Makeover at Yahoo! HotJobs
> http://hotjobs.sweepstakes.yahoo.com/careermakeover
> _______________________________________________
> Groff maillist  -  address@hidden
> http://ffii.org/mailman/listinfo/groff