-h, --help option

[anatoly techtonik]

Enough work? Is the main problem in that ssh option parsing code doesn't
support long options and doing this in C in cross-platform manner doesn't
worth the development time?

Maybe the problem is that people are not interested to do this work,
because it simply doesn't affect them?

On Tue, Jun 24, 2014 at 2:48 PM, Markus Friedl <mfriedl at gmail.com> wrote:
> 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



-- 
anatoly t.