-h, --help option

[anatoly techtonik]

On Mon, Jun 23, 2014 at 6:11 PM, Ben Lindstrom <mouring at eviladmin.org> 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.

Manual page is a separate issue. I don't skip it just to make sure the
point is covered.

`ssh` on Windows comes with git from this package -
http://msysgit.github.io/ because it highly depends on other Linux tools.
The archive is 15Mb with 246Mb unpacked. The only manual shipped
is HTML formatted man pages for Git itself. Including manuals for other
146 binary files from its /bin path would bloat the installation significantly.

Git neglected Windows platform for a long time, but in the end they took
usability on this platform seriously. HTML pages are more usable than
man, just because we are all familiar with browsers and know where
is their search button.

>> 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.

Again. Command line help is not documentation.
- command line help is a one page reference.
- documentation is a hundred(s) page description

I don't see how maintaining a single page of human readable
option description is more painful than maintaining hundred
pages of C code that parses these options.

--help page will be updated once in few years. Command line help is
usually autogenerated, and libs like docopt even build commandline
interface from its human description.

> 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.

2.1. No need to sum up a lot of options - for --help only the most
used/most important ones are needed
2.2. Minor tricks that burn users by default is an indicator of
complex and maybe complicated interface, so an attempt to sum up the
interface may lead to new ideas for refactoring to make it more
suitable for humans.

It may be more fruitful if you reply to original letter and comment on
output example.

> I agree with Markus that most --help ends up being a lie as it barely explains the meaning of the options a lot of times, and in the end I still have to dig up the manpage so they just cost more time for the developer.

With such logic I can say that any non-expanded clause a lie, because
it misses details. However, command line reference is never meant to
be complete and contain them. Again, take git is an example. Also
you're communicating with humans, so it is completely ok to mention
'consult man page for details' in --help output.

Also, you need man page only once, to understand the concept. You can
read about it from the web, and to be honest, answers on stackoverflow
most of the time explain issues and solutions better that ssh man
pages. In my sessions command line help is invoked pretty often - at
least 1/4 of time, because I constantly work with multiple platforms -
sometimes options do not match, but more often I just forget them.

-- 
anatoly t.