Added support to fish_opt for defining a long flag with no short flag.

Specifically, this now makes the -s/--short option to fish_opt optional when the
-l/--long option is given. This commit does not modify argparse, as it already
supports defining long flags without a corresponding short flag, however
fish_opt would never take advantage of this feature.

Note that due to a limitation in argparse, fish_opt will give an error if you
try to define a one-character --long flag without also providing a --short
option.

For backwards compatibility, the --long-only flag is still included with
fish_opt, and when used with -s/--short, will behave as before (the short flag
is still defined, but argparse will fail if it is actually used by the parsed
arguments, moreover the _flag_ option variables will not be defined). This can
however be used to define a one character long flag.

doc_src/cmds/argparse.rst

@@ -136,9 +136,11 @@ Option Specifications
 
 Each option specification consists of:
 
-- An optional alphanumeric short flag character, followed by a ``/`` if the short flag can be used by someone invoking your command or, for backwards compatibility, a ``-`` if it should not be exposed as a valid short flag (in which case it will also not be exposed as a flag variable).
+- An optional alphanumeric short flag character.
 
-- An optional long flag name, which if not present the short flag can be used, and if that is also not present, an error is reported
+- An optional long flag name, seperated from the short flag (if present) by a ``/``. If neither a short flag nor long flag are present, an error is reported.
+
+    - For backwards compatibility, if there is a short and a long flag, a ``-`` can be used in place of the ``/``, if the short flag is not to be usable by users (in which case it will also not be exposed as a flag variable).
 
 - Nothing if the flag is a boolean that takes no argument or is an integer flag, or
 

doc_src/cmds/fish_opt.rst

@@ -8,7 +8,7 @@ Synopsis
 
 .. synopsis::
 
-    fish_opt -s ALPHANUM [-l LONG-NAME] [-ormd] [--long-only]
+    fish_opt [-s ALPHANUM] [-l LONG-NAME] [-ormd] [--long-only]
     fish_opt --help
 
 Description
@@ -19,13 +19,13 @@ This command provides a way to produce option specifications suitable for use wi
 The following ``argparse`` options are available:
 
 **-s** or **--short** *ALPHANUM*
-    Takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
+    Takes a single letter or number that is used as the short flag in the option being defined. Either this option or the **--long** option must be provided.
 
 **-l** or **--long** *LONG-NAME*
-    Takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option specification.
+    Takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option specification.  If there is no **--short** flag, the long flag name must be more than one character (use **--short** together with **--long-only** to bypass this restriction).
 
 **--long-only**
-    The option being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., **--short** must be specified) but it cannot be used when parsing arguments using this option specification.
+    The option being defined will only allow the long flag name to be used, even if the short flag is defined (i.e., **--short** is specified).
 
 **-o** or **--optional-val**
     The option being defined can take a value, but it is optional rather than required. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will zero elements if no value was given with the option else it will have exactly one element.
@@ -67,7 +67,7 @@ Same as above but with a second flag that requires a value:
     argparse $options -- $argv
 
 
-Same as above but with a third flag that can be given multiple times saving the value of each instance seen and only the long flag name (``--token``) can be used:
+Same as above but with a third flag that can be given multiple times saving the value of each instance seen and only a long flag name (``--token``) is defined:
 
 
 
@@ -75,6 +75,6 @@ Same as above but with a third flag that can be given multiple times saving the
 
     set -l options (fish_opt --short=h --long=help)
     set options $options (fish_opt --short=m --long=max --required-val)
-    set options $options (fish_opt --short=t --long=token --multiple-vals --long-only)
+    set options $options (fish_opt --long=token --multiple-vals)
     argparse $options -- $argv