-h, --help option

[Markus Friedl]

Sorry, here won't be an extra --help.

The manpage and the short usage output are already enough work.

Without that focus the quality will decrease. 

-m



> Am 24.06.2014 um 09:12 schrieb anatoly techtonik <techtonik at gmail.com>:
> 
>> 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.
> _______________________________________________
> openssh-unix-dev mailing list
> openssh-unix-dev at mindrot.org
> https://lists.mindrot.org/mailman/listinfo/openssh-unix-dev