From owner-freebsd-doc@FreeBSD.ORG Thu Aug 19 12:50:18 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 24B8716A4D0 for ; Thu, 19 Aug 2004 12:50:18 +0000 (GMT) Received: from internet.potentialtech.com (h-66-167-251-6.phlapafg.covad.net [66.167.251.6]) by mx1.FreeBSD.org (Postfix) with ESMTP id EA87443D1F for ; Thu, 19 Aug 2004 12:50:17 +0000 (GMT) (envelope-from wmoran@potentialtech.com) Received: from working.potentialtech.com (pa-plum-cmts1e-68-68-113-64.pittpa.adelphia.net [68.68.113.64]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by internet.potentialtech.com (Postfix) with ESMTP id 03EA369A71; Thu, 19 Aug 2004 08:50:16 -0400 (EDT) Date: Thu, 19 Aug 2004 08:50:15 -0400 From: Bill Moran To: Anthony Duerr Message-Id: <20040819085015.73799dca.wmoran@potentialtech.com> In-Reply-To: <41249BC4.7000205@pushitlive.net> References: <41249BC4.7000205@pushitlive.net> Organization: Potential Technologies X-Mailer: Sylpheed version 0.9.12 (GTK+ 1.2.10; i386-portbld-freebsd4.9) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit cc: freebsd-doc@freebsd.org 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 12:50:18 -0000 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. -- Bill Moran Potential Technologies http://www.potentialtech.com