From owner-freebsd-doc@FreeBSD.ORG Thu Aug 19 12:37:52 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 EBB6716A4CE for ; Thu, 19 Aug 2004 12:37:52 +0000 (GMT) Received: from abigail.blackend.org (blackend.org [212.11.35.229]) by mx1.FreeBSD.org (Postfix) with ESMTP id 206AC43D49 for ; Thu, 19 Aug 2004 12:37:52 +0000 (GMT) (envelope-from marc@blackend.org) Received: from abigail.blackend.org (localhost [127.0.0.1]) i7JCboLG024572; Thu, 19 Aug 2004 14:37:50 +0200 (CEST) (envelope-from marc@abigail.blackend.org) Received: (from marc@localhost) by abigail.blackend.org (8.12.11/8.12.11/Submit) id i7JCbjeg024571; Thu, 19 Aug 2004 14:37:45 +0200 (CEST) (envelope-from marc) Date: Thu, 19 Aug 2004 14:37:44 +0200 From: Marc Fonvieille To: Anthony Duerr Message-ID: <20040819123744.GG20058@abigail.blackend.org> References: <41249BC4.7000205@pushitlive.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <41249BC4.7000205@pushitlive.net> User-Agent: Mutt/1.4.2.1i X-Useless-Header: blackend.org X-Operating-System: FreeBSD 4.10-PRERELEASE 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:37:53 -0000 On Thu, Aug 19, 2004 at 07:23:32AM -0500, 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. > Many manual pages provide examples via an EXAMPLES section (look at find(1), bsdlabel(8), etc.). We just need someone to write missing EXAMPLES sections :) Marc