Documentation -- alias of second option, confusing order

[zerothi]

This is mainly a problem of the documentation:

See here: https://click.palletsprojects.com/en/8.1.x/options/#boolean-flags

I find this:

If you want to define an alias for the second option only, then you will need to use leading whitespace to disambiguate the format string:

Example:

import sys

@click.command()
@click.option('--shout/--no-shout', ' /-S', default=False)
def info(shout):
    rv = sys.platform
    if shout:
        rv = rv.upper() + '!!!!111'
    click.echo(rv)

info --help
Usage: info [OPTIONS]

Options:
  --shout / -S, --no-shout
  --help                    Show this message and exit.

Perhaps it's getting late here, but.. I understand it like this:

• we want to alias the 2nd option, i.e. --no-shout.
• to me the empty space before ' /-S' would mean that there is no short-hand for --shout but -S for --no-shout (that may be weird, but that's how I read it...)
• How can one then create a shorthand for --no-shout, but not --shout?

I have tried:

@click.option('--shout/--no-shout', '-S/ ', default=False)
 
$> info --help
  -S, --shout / --no-shout

Which is ok, but still a bit weird.
It seems it can only be used to select the order of the short-hand function for the documentation.
Perhaps this is intended, but I find the above quite confusing?

[j7an]

@zerothi Your following assumption is correct.

to me the empty space before ' /-S' would mean that there is no short-hand for --shout but -S for --no-shout (that may be weird, but that's how I read it...)

The following

@click.option('--shout/--no-shout', ' /-S', default=False)

returns darwin which agrees with your understanding of the documentation

The following

@click.option('--shout/--no-shout', '-S/ ', default=False)

returns DARWIN!!!!111 which is the --shout flag. Your own help output also shows the -S flag will create the same output. In this situation, the whitespace is not necessary can be shortened to '-S/', but '/-S' without the whitespace will return the following error:

Error: No such option: -S

This appears to be working correctly as documented.

[zerothi]

@j7an the problem is that the --help shows:

Options:
  --shout / -S, --no-shout

which makes me think that -S belongs to --shout, but it doesn't... It belongs to --no-shout?
I think it is because the / is used as the delimiter, but I think that delimiter is generally understood as or, e.g. --shout / -S, I would interpret (dare I say most people) as either --shout or -S for the same option.

[davidism]

I have a feeling it will be ambiguous to someone regardless of what order or delimiters we use. I don't think we'll change it at this time.