Re: completing .directories without . and ..

[Roman Perepelitsa <roman.perepelitsa@gmail.com>]

On Tue, Feb 21, 2023 at 5:59 PM Thomas Lauer <thomas.lauer@virgin.net> wrote:
>
> From: Roman Perepelitsa <roman.perepelitsa@gmail.com>
> Date: Tue, 21 Feb 2023 17:48:44 +0100
> > See "special-dirs" in `man zshcompsys` for documentation.
>
> Right. I knew it was something simple but all my attempts to find that
> simple thing were getting nowhere.

Here's a hypothetical yet plausible way how you could've found it.

First, look at `man zsh`. At the very top it has an index. Given that
you are trying to customize completions, there are 3 candidates that
mention completions:

    zshcompwid   Zsh completion widgets
    zshcompsys   Zsh completion system
    zshcompctl   Zsh completion control

zshcompctl is a trap. Hopefully you wouldn't fall for it given this
sentence at the top of it:

    New users of the shell may prefer to use the newer and more
    powerful system based on shell functions; this is described in
    zshcompsys(1), and the basic shell mechanisms which
    support it are described in zshcompwid(1).

This hints that zshcompwid isn't what you want either. Let's check it anyway:

    A  complete set of shell functions based on these features is
    described in zshcompsys(1), and users with no interest in
    adding to that system (or, potentially, writing their own -- see
    dictionary entry for `hubris') should skip the current section.
    The older system based on the compctl builtin command is
    described in zshcompctl(1).

This confirms that zshcompctl is a trap that you should avoid, and
that zshcompwid describes the low level API on top of which the
user-facing zshcompsys is built.

Hopefully, eventually you would've looked at zshcompcsys. Searching
".." would then land you on special-dirs fairly quickly.

Note that if you already knew that the user-facing docs for
completions are in zshcompsys, the search would be fairly
straightforward.

There are only 9 zsh man pages that I ever look at (plus zshall if I'm
unsure which one I need), and I remember their names by now. Before I
learned them, I often opened `man zsh` to see the list of section
names with short descriptions.


Roman.