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

[Oliver Kiddle <opk@xxxxxxx>]

On 20 May, dana wrote:
> do you just disagree with the wording/characterisation of that part? i
> can drop it if that's all (attached). or you'd prefer another direction
> entirely? or you think it's already as clear as it needs to be?

Sorry, I never replied to this at the time and am trying to catch up.

> diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
> index 06b08cc72..d9f151871 100644
> --- a/Doc/Zsh/compsys.yo
> +++ b/Doc/Zsh/compsys.yo
> @@ -3743,11 +3743,12 @@ argument, and the `tt(-)tt(-)' is considered to be neither.
>  )
>  item(tt(-A) var(pat))(
>  Do not complete options after the first non-option
> -argument on the line.  var(pat) is a pattern matching
> -all strings which are not to be taken as arguments.  For example, to make
> -tt(_arguments) stop completing options after the first normal argument, but
> -ignoring all strings starting with a hyphen even if they are not described
> -by one of the var(optspec)s, the form is `tt(-A "-*")'.
> +argument on the line.  Any such argument that matches var(pat)
> +is ignored (as if it didn't appear on the line) until another
> +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(optspec)s as a non-option argument.
>  )
>  item(tt(-O) var(name))(
>  Pass the elements of the array var(name) as arguments to functions called to

My objection to this is that it describes a side-effect rather than the
primary function of -A.

The wording in the 3.1.9 documentation seems clearer to me and perhaps
makes the original intent more apparent:

    To simplify the specifications for commands with standard option
    parsing, the options tt(-A) and tt(-S) may be given. With tt(-A) no
    options will be completed after the first non-option argument on the
    line. With tt(-S), no option will be completed after a `tt(-)tt(-)' on 
    the line and this argument will otherwise be ignored.

By 3.1.9-dev-8 details of the pattern have been added.

The side-effect of ignoring extra arguments that do match the pattern
exists because it is always better to handle the situation of missing
option specs gracefully.

Arguably, this could have been implemented in a more generic manner so
that unknown options can be ignored for GNU style parsers too.

This is not to say that the documentation can't be improved.

Oliver