Re: How does a new software package provide Zsh tab completion scripts to users?

[Phil Pennock <zsh-workers+phil.pennock@spodhuis.org>]

On 2013-04-23 at 16:21 -0500, Robert McLay wrote:
> I am the author of a software package and I'd like to provide Zsh tab
> completion scripts for users of my package.

Option 1: get added to zsh
  Upsides:
    * always available
  Downsides:
    * only available by default with new versions
    * decoupled from the version actually installed
  Summary:
    * works best when API is stable and you're able/willing to let
      others handle maintenance

For the rest of this, I'll assume you don't want to just supply the
completion for inclusion with zsh, but it's probably still the best
option for you.

What should typically happen is that the OS build of zsh uses
`./configure --site-fndir=...` to supply some directory which collects
packages/other scripts, which will result in the default $FPATH/$fpath
in zsh having an extra directory to check.

Option 2: include in a contrib/ or misc/ directory, document
  Upsides:
    * You maintain complete control
    * Can vary incompatibly
  Downsides:
    * Needs you to communicate clearly to packagers that there's a file
      they should drop into the zsh site function directory (perhaps via
      symlink)
    * You need to figure out how far back in zsh terms you want to be
      compatible and write portable zsh; for common features, this
      shouldn't be an issue, but it's worth remembering that you can't
      just use whatever facilities are added to make life easier for
      you, whereas those who get the functions added to zsh can

Eg, on FreeBSD, the portupgrade tool just unilaterally installs the file
share/zsh/site-functions/_pkgtools (relative to the install-base) and if
zsh is installed, before or after, then the extra completions just
become available.

Option 3: user installation, no control of zsh or system install
  Upsides:
    * no coordination with anyone but user
  Downsides:
    * coordination with end users

Tell people to link to the file inside an element of $fpath which they
control and to do so before starting completion configuration.  Tell
them that this won't be necessary with appropriate system configuration,
link to the document explaining how to get the completion set up in
system directories, let the users buy the sysadmins beer until the local
installs are fixed.


A little more seriously: there's a decision tree:

  1: Does user admin their own system?

  1=Yes:
    2: Is user an experienced Unix user?
      2=No: User should be using package management (option 2)
      2=Yes: User should be using package management (option 2)
             but they have a fallback to option 3

  1=No:
    3: Are there sysadmins?
      3=Yes: Option 2 applies, the persuasion mentioned above
      3=No: give up, they're doomed