From owner-freebsd-doc@FreeBSD.ORG Thu Aug 19 19:44:05 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 2DCC616A4CE; Thu, 19 Aug 2004 19:44:05 +0000 (GMT) Received: from mail.pushitlive.net (mail.pushitlive.net [24.106.18.115]) by mx1.FreeBSD.org (Postfix) with ESMTP id B212143D45; Thu, 19 Aug 2004 19:44:04 +0000 (GMT) (envelope-from duerra@pushitlive.net) Received: from [127.0.0.1] (unknown [209.181.253.173]) by mail.pushitlive.net (Postfix) with ESMTP id B3769261AB4; Thu, 19 Aug 2004 14:43:59 -0500 (CDT) Message-ID: <412502EE.8070507@pushitlive.net> Date: Thu, 19 Aug 2004 14:43:42 -0500 From: Anthony Duerr User-Agent: Mozilla Thunderbird 0.7.3 (Windows/20040803) X-Accept-Language: en-us, en MIME-Version: 1.0 To: Bill Moran References: <41249BC4.7000205@pushitlive.net> <20040819085015.73799dca.wmoran@potentialtech.com> <20040819112808.52f7bdc5@localhost.pittgoth.com> <20040819150125.4fbae6e2.wmoran@potentialtech.com> In-Reply-To: <20040819150125.4fbae6e2.wmoran@potentialtech.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit cc: Tom Rhodes 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 19:44:05 -0000 Bill Moran wrote: >Tom Rhodes wrote: > > >>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; >> >> > >Can't do that. > > > >>2: Some example sections would be dubious (rc.conf, make.conf, etc); >> >> > >Agreed. Many daemons don't need example sections, such as ftpd, etc. > >This was why I recommended he point out the particular man page(s) that >he thought needed examples. > > > >>3: Personally, I honestly don't have the time for a project >> like this. Sorry. >> >> > >Oh, come on. You're not doing anything else important ... I'll tell you >what ... take the time you spend chasing women around and cut it in half. >You'll still be getting way more sex than me, and you'll have a ton of >extra time to work on FreeBSD stuff! > > Thanks for your replies. I was actually referring to the man pages in general. Prototypes can get somewhat confusing rather easily if you're not well versed. Here's the prototype from scp: scp [-pqrvBC1246] [-F ssh_config] [-S program] [-P port] [-c cipher] [-i identity_file] [-l limit] [-o ssh_option] [[user@]host1:]file1 [...] [[user@]host2:]file2 Now, this one isn't really that bad. After you figure it out, it makes complete sense. Sometimes the sub-options ( [[[ ]]]) can get rather deep, though, and start to become really confusing (especially for lesser experienced users like myself). I realize that changing all the man pages is not going to happen. I don't see a particular need for them to all be sludged through, but rather when the man pages are updated, something like that could be added as well. In the case of scp, something like this: Examples: scp -r username@remotehost.com: /path/to/local/dir/ /path/to/remote/dir /* This recursively copies a local directory to a remote directory using the current user */ scp username@remotehost.com: /a/file.txt /remote/directory/file.txt /* This copies local file "file.txt" to /remote/directory/file.txt */ Now, the example above isn't exactly flawless, but you get the idea. And yes, I do realize that this wouldn't be necessary for all man pages. It would be useful for many applications, however. Thanks!