Update the docs for complete

* Indicate which options can be repeated in the usage lines.
* Reorder the options in usage slightly to group better.
* Reorder the option descriptions to match the order as seen in usage.
* Update some of the option descriptions.
* Fix the documentation for -C to show that it must be `-CSTRING`
  instead of `-C STRING`.
* Document the behavior of `-C` with no argument.
* Tweak some of the explanatory text after the option list.
* Delete `--authoritative` and `--unauthoritative` from the
  documentation entirely. Those options appear to not actually do
  anything in the new parser.

doc_src/complete.txt

@@ -3,19 +3,18 @@
 \subsection complete-synopsis Synopsis
 \fish{synopsis}
 complete ( -c | --command | -p | --path ) COMMAND
+        [( -c | --command | -p | --path ) COMMAND]...
         [( -e | --erase )]
-        [( -s | --short-option ) SHORT_OPTION]
-        [( -l | --long-option | -o | --old-option ) LONG_OPTION]
+        [( -s | --short-option ) SHORT_OPTION]...
+        [( -l | --long-option | -o | --old-option ) LONG_OPTION]...
+        [( -a | --arguments ) OPTION_ARGUMENTS]
         [( -f | --no-files )]
         [( -r | --require-parameter )]
         [( -x | --exclusive )]
-        [( -u | --unauthoritative )]
-        [( -A | --authoritative )]
-        [( -a | --arguments ) OPTION_ARGUMENTS]
-        [( -w | --wraps ) WRAPPED_COMMAND]
+        [( -w | --wraps ) WRAPPED_COMMAND]...
         [( -n | --condition ) CONDITION]
         [( -d | --description ) DESCRIPTION]
-complete ( -C STRING | --do-complete=STRING )
+complete ( -C[STRING] | --do-complete[=STRING] )
 \endfish
 
 \subsection complete-description Description
@@ -34,27 +33,33 @@ the fish manual.
 
 - `DESCRIPTION` is a description of what the option and/or option arguments do.
 
-- `-C STRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string.
+- `-c COMMAND` or `--command COMMAND` specifies that `COMMAND` is the name of the command.
 
-- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command.
+- `-p COMMAND` or `--path COMMAND` specifies that `COMMAND` is the absolute path of the program (optionally containing wildcards).
 
 - `-e` or `--erase` deletes the specified completion.
 
-- `-f` or `--no-files` specifies that the option specified by this completion may not be followed by a filename.
+- `-s SHORT_OPTION` or `--short-option=SHORT_OPTION` adds a short option to the completions list.
+
+- `-l LONG_OPTION` or `--long-option=LONG_OPTION` adds a GNU style long option to the completions list.
+
+- `-o LONG_OPTION` or `--old-option=LONG_OPTION` adds an old style long option to the completions list (See below for details).
+
+- `-a OPTION_ARGUMENTS` or `--arguments=OPTION_ARGUMENTS` adds the specified option arguments to the completions list.
+
+- `-f` or `--no-files` specifies that the options specified by this completion may not be followed by a filename.
+
+- `-r` or `--require-parameter` specifies that the options specified by this completion always must have an option argument, i.e. may not be followed by another option.
+
+- `-x` or `--exclusive` implies both `-r` and `-f`.
+
+- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command (See blow for details).
 
 - `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
 
-- `-o` or `--old-option` implies that the command uses old long style options with only one dash.
+- `-CSTRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string.
 
-- `-p` or `--path` implies that the string `COMMAND` is the full path of the command.
-
-- `-r` or `--require-parameter` specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option.
-
-- `-u` or `--unauthoritative` implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors.
-
-- `-A` or `--authoritative` implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors.
-
-- `-x` or `--exclusive` implies both `-r` and `-f`.
+- `-C` or `--do-complete` with no argument makes complete try to find all possible completions for the current command line buffer. If the shell is not in interactive mode, an error is returned.
 
 Command specific tab-completions in `fish` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are:
 
@@ -62,13 +67,17 @@ Command specific tab-completions in `fish` are based on the notion of options an
 
 - Old style long options, like '`-Wall`'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('`-ao null`').
 
-- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h').
+- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style shell`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h').
 
-The options for specifying command name, command path, or command switches may all be used multiple times to specify multiple commands which have the same completion or multiple switches accepted by a command.
+The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands.
+
+The options for specifying command switches and wrapped commands may be used multiple times to define multiple completions for the command(s) in a single call.
+
+Invoking `complete` multiple times for the same command adds the new definitions on top of any existing completions defined for the command.
 
 The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the `-e` or `--erase` options.
 
-When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -e -c COMMAND`, or by specifying a specific completion option to delete by specifying either a long, short or old style option.
+When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -c COMMAND -e`, or by specifying a specific completion option to delete by specifying either a long, short or old style option.
 
 
 \subsection complete-example Example
@@ -99,7 +108,7 @@ This can be written as:
 complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies"
 \endfish
 
-where `__fish_contains_opt` is a function that checks the commandline buffer for the presence of a specified set of options.
+where `__fish_contains_opt` is a function that checks the command line buffer for the presence of a specified set of options.
 
 To implement an alias, use the `-w` or `--wraps` option: