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

[Meg McRoberts]

--- Larry Kollar <address@hidden> wrote:

> Meg McRoberts:
> > 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. :-(

Yes, I think you're right that the *roff manpages were traditionally
one of the weaker parts of the manpage set.  The groff pages are MUCH
better than the old AT&T pages!  As I recall, the vi(1) page was also
not a model of what a manpage should be.  To be fair, the whole *roff
toolset kind of floated in limbo for a lot of years while people were
gradually improving the documentation for the rest of the O/S.  I was
at Bell Labs in the mid-80's and I remember that there were a couple
truly annoying bugs in tbl that many people knew how to fix but noone
could ever figure out who owned the source to go in and do the fixes!

> 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?

If I have access to the manpage source, I like to do `grep "\.S" ' to
see the basic structure of the page -- .SH/.SS.  I don't know of a way
to get that structural info from formatted manpages, alas.

> > 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...

Just to clarify, I said that a _basic_ manpage was easy to write.  Someone
implements a new command/function/file/structure...  Define the syntax; write
a "Description" that tells what this item is for and so forth;
list and define all the options/arguments/fields/members; define the return/
error values/messages; stick in a "See also" section that references related
commands/functions/files/members; for bonus points, throw in a couple examples
and you have a basic manpage.  And, in the heat of battle, having just this
much written down does provide a fair amount of useful information; when
resources are short, one can survive reasonably well if this is all that
happens.

A good writer who invests some thought can do a lot more to make a manpage
more useful, but I always figured that, if resources were tight, if one
didn't do anything more than this, one could survive.  And this requires
a great deal of insight, skill, thought, and work to do.

> 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.

Precisely!  

> > 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....

Yes, this tone is very evident in the draft I saw -- this is a very good
thing.

meg

> --
> 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 maillist  -  address@hidden
> http://ffii.org/mailman/listinfo/groff



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