Date: Thu, 19 Aug 2004 16:45:55 -0400 From: Tom Rhodes <trhodes@FreeBSD.org> To: Anthony Duerr <duerra@pushitlive.net> Cc: freebsd-doc@FreeBSD.org Subject: Re: Man Pages Thoughts 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>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 19 Aug 2004 14:43:42 -0500 Anthony Duerr <duerra@pushitlive.net> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040819164555.1dfb9cab>