-h, --help option

[Corinna Vinschen]

On Jun 23 10:11, Ben Lindstrom wrote:
> On Jun 23, 2014, at 5:48 AM, anatoly techtonik <techtonik at gmail.com> wrote:
> 
> > I can argue that man pages are absent at least on Windows, but it does
> > not matter here, because comparing manual with command line help is
> > wrong.
> 
> That would be an issue you should take up with the whomever packaged your ssh for windows.
> 
> > In other words --help option is not a replacement for a full doc and it is
> > not meant to provide detailed information about software. However, it
> > provides a useful reference for most used options. See git for example,
> > which provides both.
> 
> The issue with this is two fold:
> 
> 1. Keep the documentation up in two places is more painful than one.
> 2. Attempting to sum up a lot of the ssh options via one-liners becomes pretty hard as even a paragraph or two in the manage doesn't always fully explain the minor ticks that may burn you if you aren't reading carefully.

In a somewhat twisted way, --help already works ;-)

  $ scp --help
  scp: unknown option -- -
  usage: scp [-12346BCpqrv] [-c cipher] [-F ssh_config] [-i identity_file]
	     [-l limit] [-o ssh_option] [-P port] [-S program]
	     [[user@]host1:]file1 ... [[user@]host2:]file2
 
As for one-liner help output, we already have two noticable exceptions
from this rule:

  $ ssh-agent --help
  ssh-agent: unknown option -- -
  usage: ssh-agent [options] [command [arg ...]]
  Options:
    -c          Generate C-shell commands on stdout.
    -s          Generate Bourne shell commands on stdout.
    -k          Kill the current agent.
    -d          Debug mode.
    -a socket   Bind agent socket to given name.
    -t life     Default identity lifetime (seconds).

  $ ssh-keygen --help
  ssh-keygen: unknown option -- -
  usage: ssh-keygen [options]
  Options:
    -A          Generate non-existent host keys for all key types.
    -a number   Number of KDF rounds for new key format or moduli primality tests.
    -B          Show bubblebabble digest of key file.
    -b bits     Number of bits in the key to create.
    [...]

Whatever you guys think about this kind of help output, from my point of
view the more helpful(!) help output of ssh-keygen was often a
life-saver.  Also, a more helpful help output is still a *lot* faster
over a slow remote connection than having to call `man'.  And sometimes
man pages aren't even installed on systems with tight filesystems.


Just my 2ct,
Corinna

-- 
Corinna Vinschen
Cygwin Maintainer
Red Hat
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.mindrot.org/pipermail/openssh-unix-dev/attachments/20140625/c6ec65ed/attachment.bin>