[Pkg-zsh-devel] Installing zsh completion files

[Frank Terbeck]

William Giokas wrote:
> On Wed, Jul 24, 2013 at 03:48:41PM +0200, Frank Terbeck wrote:
>> Felipe Sateler wrote:
>> > While zsh provides great completion functions for many programs,
>> > sometimes a better one is crafted by the program authors. Where should
>> > a program install the completion file? It seems to me that
>> > /u/s/zsh/vendor-completions is the correct place, but I wanted to
>> > confirm that.
>> 
>> For other debian packages that is precisely the intended location to
>> install additional completion functions. The two directories
>> `vendor-completions' and `vendor-functions' are located very early in
>> $fpath, so that anything in them overrides any function of the same
>> name, that zsh may ship.
>
> I would just warn you that debian seems to be the only distribution that
> thinks about using vendor-functions. And looking through your packages,
> you have me confused. Using apt-file, I found nothing in
> /usr/share/zsh/vendor-functions/ in any package.

We have added the directory after someone specifically asked for a place
to install completion files to:

  http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=620452

People may be using the directories with private packages, like the
submitter of the bug.

Introducing the directories makes sense, because it allows upstream, us
packagers and admins a maximum amount of control of function files:

  1. If the file is in /usr/local/share/zsh/site-functions it is used
     (this is the the-admin-always-wins option) no matter what.

  2. If the file is in one of the debian-specific "vendor-*"
     directories, any package different from zsh may add new or override
     functions shipped with zsh (this is the
     distribution-overrules-upstream option).

  3. If the two previous options don't trigger, use zsh's functions from
     the rest of its $fpath (this is the fall-back-to-zsh option).

> I have no idea how
> reliable that is, but I also have no vendor-functions on my system.

There is nothing to warn about. The `vendor-functions' directory is only
of concern for debian packages. And the maintainer of the package needs
to make sure it is used.

Starting with debian's 4.3.12-1 packages these directories are active.
And they will remain active, because it makes sense for us as a vendor
to provide directories like that, as I outlined above.

> zsh
> should, by default, be installing its completions to
> $prefix/share/zsh/$version.

It shouldn't. For example, that wouldn't work if zsh was compiled with
the `--enable-function-subdirs' compile-time option to remedy the
one-directory-full-of-everything approach:

/usr/local/share/zsh/5.0.2/functions/Calendar
/usr/local/share/zsh/5.0.2/functions/Chpwd
/usr/local/share/zsh/5.0.2/functions/Completion
/usr/local/share/zsh/5.0.2/functions/Completion/AIX
/usr/local/share/zsh/5.0.2/functions/Completion/Base
/usr/local/share/zsh/5.0.2/functions/Completion/BSD
/usr/local/share/zsh/5.0.2/functions/Completion/Cygwin
/usr/local/share/zsh/5.0.2/functions/Completion/Darwin
/usr/local/share/zsh/5.0.2/functions/Completion/Debian
/usr/local/share/zsh/5.0.2/functions/Completion/Linux
/usr/local/share/zsh/5.0.2/functions/Completion/Mandriva
/usr/local/share/zsh/5.0.2/functions/Completion/openSUSE
/usr/local/share/zsh/5.0.2/functions/Completion/Redhat
/usr/local/share/zsh/5.0.2/functions/Completion/Solaris
/usr/local/share/zsh/5.0.2/functions/Completion/Unix
/usr/local/share/zsh/5.0.2/functions/Completion/X
/usr/local/share/zsh/5.0.2/functions/Completion/Zsh
/usr/local/share/zsh/5.0.2/functions/Exceptions
/usr/local/share/zsh/5.0.2/functions/MIME
/usr/local/share/zsh/5.0.2/functions/Misc
/usr/local/share/zsh/5.0.2/functions/Newuser
/usr/local/share/zsh/5.0.2/functions/Prompts
/usr/local/share/zsh/5.0.2/functions/TCP
/usr/local/share/zsh/5.0.2/functions/VCS_Info
/usr/local/share/zsh/5.0.2/functions/VCS_Info/Backends
/usr/local/share/zsh/5.0.2/functions/Zftp
/usr/local/share/zsh/5.0.2/functions/Zle

Debian builds its packages like that and personally, I'm doing that as
well.

Regards, Frank

-- 
In protocol design, perfection has been reached not when there is
nothing left to add, but when there is nothing left to take away.
                                                  -- RFC 1925