From owner-freebsd-doc@FreeBSD.ORG Thu Aug 19 15:27:33 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id D359416A4CE for ; Thu, 19 Aug 2004 15:27:33 +0000 (GMT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id 64D0A43D5D for ; Thu, 19 Aug 2004 15:27:33 +0000 (GMT) (envelope-from trhodes@FreeBSD.org) Received: from localhost.pittgoth.com (acs-24-154-239-170.zoominternet.net [24.154.239.170]) (authenticated bits=0) by pittgoth.com (8.12.10/8.12.10) with ESMTP id i7JFRVVF004423 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Thu, 19 Aug 2004 11:27:32 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Thu, 19 Aug 2004 11:28:08 -0400 From: Tom Rhodes To: Bill Moran Message-Id: <20040819112808.52f7bdc5@localhost.pittgoth.com> In-Reply-To: <20040819085015.73799dca.wmoran@potentialtech.com> References: <41249BC4.7000205@pushitlive.net> <20040819085015.73799dca.wmoran@potentialtech.com> X-Mailer: Sylpheed-Claws 0.9.12 (GTK+ 1.2.10; i386-portbld-freebsd5.2) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit cc: freebsd-doc@FreeBSD.org cc: Anthony Duerr Subject: Re: Man Pages Thoughts X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 19 Aug 2004 15:27:33 -0000 On Thu, 19 Aug 2004 08:50:15 -0400 Bill Moran wrote: > Anthony Duerr 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