Re: [PATCH] docs: clarify `_arguments -A` behaviour

[Oliver Kiddle <opk@xxxxxxx>]

dana wrote:
> i hope this is clearer

Am not sure it is especially.

>  Do not complete options after the first non-option
> +argument on the line.  Any such argument that matches var(pat)
> +is ignored (as if it didn't appear on the line) until another

Saying it is "ignored" could imply a wider effect.

> +non-option argument is encountered that doesn't match it.  This
> +is most often used in the form `tt(-A "-*")' to prevent the
> +function from treating an option not described by one of the
> +var(optspecs) as a non-option argument and refusing to complete
> +further options, which might be annoying.

The words "refusing" and "annoying" give this an overly conversational
tone for a manual without adding clarity. It does not complete further
options because they would be unwanted.

Perhaps it is simpler if we try to keep things in terms of how different
command-line parsers work. The traditional Unix convention was that the
first non-option argument would terminate the options. The -A option
helps to identify this first non-option argument by using a pattern. The
opt-specs are used too and are especially relevant to options that take
an argument. I'd guess it doesn't only rely on the opt-specs because
a pattern allows for more graceful behaviour where the opt-specs are
incomplete. You may also see "[-+]*" as the pattern where + options
are used. The feature might have been simpler to understand if the
pattern was negated but then we'd mostly be using "^-*" as the pattern
instead. Allowing options to follow non-option arguments was largely a
GNU convention to allow more flexibility. But that forces greater use
of -- to terminate options.

Oliver