bug#13737: Add -h option to 'users'

[anatoly techtonik]

On Mon, Feb 18, 2013 at 11:57 PM, Eric Blake <address@hidden> wrote:

> On 02/18/2013 01:31 PM, anatoly techtonik wrote:
> >> We HAVE documented it.  We document that ALL long options can be
> >> represented by an unambiguous prefix, so --h is an unambiguous prefix of
> >> --help if there are no other long options beginning with h.
> >
> > Is it a part of POSIX, RedHat or just usual man page for 'users'? Can you
> > post a proof link here?
>
> Long options are not specified by POSIX.  But they are commonly
> implemented by getopt_long(), which documents the GNU-standard behavior
> of recognizing unambiguous prefix.  The glibc manual doesn't document
> prefix handling (arguably a bug in glibc documentation, but that is not
> a question for this list):
>
> https://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html#Getopt-Long-Options
>
> but the Linux man pages DO document abbreviations:
> http://linux.die.net/man/3/getopt_long
> "Long option names may be abbreviated if the abbreviation is unique or
> is an exact match for some defined option."
>
> Coreutils also documents it here:
> https://www.gnu.org/software/coreutils/manual/coreutils.html#Common-options
>
> which is very near the beginning of 'info coreutils', our preferred
> documentation system.


It is documented that "most programs recognize unambiguous abbreviations"
of long options, but these are not POSIX standards, not a recommendation
either - just a feature of getopt parser. To me it looks like the usability
choice is affected by the internal implementation of option parsing
library, not really a choice if you ask me. Python option parsing went long
way getopt -> optparse -> argparse -> docopt since the time getopt was
invented, and the "-h" option is the current best practice.

And I really doubt that much users nowadays have a chance to run over this
chapter in coreutils manual. 95% of the target documentation audience reads
stackoverflow nowadays. Therefore, how many users are actually aware of
"--h" option and intuitively use it instead of "-h"? I can't answer this
question without the poll, but I can suspect that "--h" doesn't work in
majority of unix commands provided by scripts.

>
> > Do I understand it right that if OpenBSD implements "-h" - you'll copy?
>
> Yes, if there is existing practice of burning '-h' to mean help in some
> other implementation, then the option cannot be standardized by POSIX to
> mean anything else, so we might as well also make it mean help.  But we
> aren't going to lead the pack on burning a short option for something
> like help.


And if I say that the whole cross-platform Python stack burned "-h, --help"
as default options of providing help to console scripts? This goes way
beyond OpenBSD and even POSIX. Is that enough?


> > I don't get why GNU development and usability features should depend on
> > non-GNU implementation?
>
> GNU prefers long options.  We support short options insofar as standards
> documents and compatibility dictate, but don't let short options drive
> development.


That's a good policy. "-h" is already a well matured practice to be
implemented, and I doesn't see any dictatorship documents that directly
stand against it. =)