Man Pages Thoughts

[Tom Rhodes]

On Thu, 19 Aug 2004 14:43:42 -0500
Anthony Duerr <duerra at 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 at 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 at 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