[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Groff] Effective manpages, a couple of thoughts
From: |
Meg McRoberts |
Subject: |
Re: [Groff] Effective manpages, a couple of thoughts |
Date: |
Tue, 11 May 2004 02:25:41 -0700 (PDT) |
--- 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
- [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, 2004/05/10
- Re: [Groff] Effective manpages, a couple of thoughts,
Meg McRoberts <=
- 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