Man Pages Thoughts

[Tom Rhodes]

On Thu, 19 Aug 2004 08:50:15 -0400
Bill Moran <wmoran at potentialtech.com> wrote:

> Anthony Duerr <duerra at pushitlive.net> wrote:
> 
> > Greetings,
> > My thoughts are concerning the man pages.  I don't know if this is the 
> > perfect group to mail this to, but it seems to be as close as I could get.
> > 
> > Anyway, a thought occured to me this morning when reading through some 
> > documentation.  It would be great to see an "Examples" section in the 
> > man pages.  Often times the prototypes are difficult to read or 
> > understand because of their length, option depth, etc.  An "Examples" 
> > area in the man pages would allow the man creator to put in a couple of 
> > the more commonly used prototypes examples in to get a user started on 
> > the right track.
> > 
> > Granted, this would mostly be beneficial to newer users like me, but it 
> > would save quite a bit of frustration when trying to process the vast 
> > array of different commands in my mind.
> > 
> > I'm interested in your thoughts!
> 
> As already stated, many man pages do contain an examples section.  This
> section is optional.
> 
> If you could point out which man pages are lacking examples, it's likely
> that you could get some folks motivated to add an examples section to
> them.

%pwd
/usr/src
%find . -name '*.[1-9]' | xargs grep 'EXAMPLES' | wc -l
	493
%find . -name '*.[1-9]' | wc -l
	2892

So basically, you only need to fix 2399 manual pages;

NOTES:

1: This counts files in contrib;
2: Some example sections would be dubious (rc.conf, make.conf, etc);
3: Personally, I honestly don't have the time for a project
   like this.  Sorry.

-- 
Tom Rhodes