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

From: anatoly techtonik <[email-masked]>
Date: Mon, 18 Feb 2013 23:58:13 +0300

On Mon, Feb 18, 2013 at 9:33 PM, Jim Meyering <[email-masked]> wrote:

> Eric Blake wrote:
> > On 02/18/2013 12:31 AM, anatoly techtonik wrote:
> >> I don't understand your argument about "unique combination". The main
> issue
> >> is that people like me expect -h to work as a --help shortcut. They
> don't
> >> have a chance to know "--h" without reading the docs, so --h is not
> useful.
> >> And by the way - this --h is not documented.
> >
> > 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.
> >
> >> The bar for adding new short options to the utilities is very high.
> >>>
> >>
> >> Sorry, but it is an argument. It will be interesting to know why though.
> >
> > We are reluctant to burn a short option letter on any utility
> > standardized by POSIX unless there are other non-GNU implementations
> > that have also burned the same letter for the same purpose.  Prematurely
> > burning a short option hinders an effort to enhance the standard;
> > whereas existing practice is a strong argument for implementing
> > something to make it easier to use GNU as a drop-in replacement that
> > gives the user freedom over the existing implementation.
> >
> >> To confirm that argument we'd have to run the poll - if the users
> expect -h
> >> to work as --help by default.
> >
> > Not generally.  The GNU coding standards mandate '--help', they do NOT
> > mandate '-h'.  More GNU users are used to '--help' than they are for any
> > short option name.
> >
> > I am against adding -h as a short option without a lot more
> > justification than just a single user, since we have had so few requests
> > for a short option -h over the years.
>
> Thanks for replying, Eric and Bob.
> One more point: a long time ago, I too thought about adding -h
> as an alias for --help for these 100-or-so programs, but even then,
> there were numerous commands for which -h was already accepted,
> but with a different meaning.
>

And that's ok. You can not be good for everyone. The usability advantage
provided by adding '-h' for showing help to 80% commands that don't have
this option outweights the _possible_ usability disadvantage of using this
option with commands that already support it for other purpose.

The usability disadvantage in this specific case is:
1. the confusion that user did't get the help
2. some state changing behavior

Let's study these specific cases.

> This command shows the affected programs:
>
>     $ grep -le -h, *.c
>     chcon.c
>     chgrp.c
>     chown-core.c
>     chown.c
>     df.c
>     du.c
>     ls.c
>     nl.c
>     pr.c
>     sort.c
>     touch.c
>

~$ chcon -h
chcon: missing operand
Try `chcon --help' for more information.

1st is not too serious - user didn't get the help - but the hint is there
  we can't do anything about it, and it can not be the reason to cancel
usability improvement
2nd is not actual as nothing changed

The following commands inhibit the same behaviour:
chgrp
chown
nl
pr
touch

Only these four commands actually do something when supplied with -h option:
df
du
ls
sort

The consequences of their execution with "-h" option are not
critical. Users running these four commands are able to figure out that
"-h" didn't work as intended and can resort to other familiar, but more
complex way of getting help. We can not change the meaning of "-h" options
for these four commands, but it is not the reason to prevent "-h" usability
improvement to other commands, including 'users'. If you're think it is the
reason, please explain why in a way that new Linux users can get it.

> Thus, we cannot do it across the board, and
> that was another reason not to do it.
>

Following Zen of Python as a good engineering practice:
...
Special cases aren't special enough to break the rules.
Although practicality beats purity.
...

I think it is exactly the case here. As you're saying it is "another
reason" - it will be good if you can summarize the reasons so far, tell if
there is something you're not convinced about and what are your concerns.
It will help to keep this focused. The original request was for the 'users'
command.

-- 
anatoly t.