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@xxxxxxxxx>: > >> On Mon, Jun 23, 2014 at 6:11 PM, Ben Lindstrom <mouring@xxxxxxxxxxxxx> wrote: >>> On Jun 23, 2014, at 5:48 AM, anatoly techtonik <techtonik@xxxxxxxxx> 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@xxxxxxxxxxx > https://lists.mindrot.org/mailman/listinfo/openssh-unix-dev _______________________________________________ openssh-unix-dev mailing list openssh-unix-dev@xxxxxxxxxxx https://lists.mindrot.org/mailman/listinfo/openssh-unix-dev
