From owner-freebsd-doc@FreeBSD.ORG Thu Aug 19 20:45:21 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 8357B16A4CE for ; Thu, 19 Aug 2004 20:45:21 +0000 (GMT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0BD1443D2D for ; Thu, 19 Aug 2004 20:45:21 +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 i7JKjIVF006573 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Thu, 19 Aug 2004 16:45:19 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Thu, 19 Aug 2004 16:45:55 -0400 From: Tom Rhodes To: Anthony Duerr Message-Id: <20040819164555.1dfb9cab@localhost.pittgoth.com> In-Reply-To: <412502EE.8070507@pushitlive.net> References: <41249BC4.7000205@pushitlive.net> <20040819085015.73799dca.wmoran@potentialtech.com> <20040819112808.52f7bdc5@localhost.pittgoth.com> <20040819150125.4fbae6e2.wmoran@potentialtech.com> <412502EE.8070507@pushitlive.net> 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 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 20:45:21 -0000 On Thu, 19 Aug 2004 14:43:42 -0500 Anthony Duerr wrote: > 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 This isn't really a 'prototype' but a command/flags/parameter list. void blah(int a, char c); Now there's a prototype. :) > > 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. Actually, this is an OpenBSD manual page and the changes should be submitted back to them. Although I agree that some manual pages would be better understood for users if they had at least one well explained example. -- Tom Rhodes