Re: zsh.texi

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

On Jun 12, 11:25pm, Mark Borges wrote:
} Subject: Re: zsh.texi
}
} Please take a look if you're interested. We would appreciate any
} suggestions or comments (or better, patches) anyone may have.

I'm just glancing at the programmable completion section at the moment.
Some of it is still pretty hard to decipher.  Here's an example:


-d This can be combined with -F, -B, -w, -a, -R and -G to get names of
       disabled functions, builtins, reserved words or aliases. 
-e Without -d this option has no effect. Otherwise this can be combined
       with -F, -B, -w, -a, -R and -G to get names of functions, builtins,
       reserved words or aliases even if they are disabled. 


That stuff under -e doesn't make sense to me -- Without -d, has no effect?
You mean I have to use `compctl -d -e ...'?  Why? -- and it conflicts with
the zshcompctl.man description:

-e Names of executable (and enabled) commands.

Here's another example:


-C controls completion when there is no current command, in other words when
       the command word itself is being completed. Without this command, the
       names of any executable command (whether in the path or specific to
       the shell, such as aliases or functions) are completed.



"Without this command, ..." ??  Without what command?  I think it means
"If no `compctl -C' command has been issued in the current shell, ...".

Then there's this:


If the + flag is alone and followed immediately by the command list, the
completion behavior for all the commands in the list is reset to its default
by deleting the command from the list of those handled specially.



I think this means:

If the + flag is alone and followed immediately by a list of command names,
any previous programmable completion for each of those commands is disabled.
This restores the default completions for the listed commands.


As a general remark, this sort of documentation should avoid talking about
how a given operation is accomplished (e.g., above, dump the "by deleting
the command from the list ... handled specially") and just state what the
end result is.  Only discuss how something works if that's important for
using the feature correctly; and even then, *first* concisely describe
the end result, and *then* elaborate how it comes to pass.

-- 
Bart Schaefer                             Brass Lantern Enterprises
http://www.well.com/user/barts            http://www.nbn.com/people/lantern

New male in /home/schaefer:
>N  2 Justin William Schaefer  Sat May 11 03:43  53/4040  "Happy Birthday"