With the term (Vim) addon we refer to an extension for the Vim editor which is not shipped with the editor itself. Examples of addons which can be frequently found on the Internet are color schemes, syntax and corresponding higlighting definitions for new languages, indentation definitions, generic and filetype-specific plugins, ...
An addon is usually composed of a set of .vim files; other kind of files, for example .txt files for documentation purposes, can be provided as well. For instance, the following files compose the vcscommand addon, providing plugins, syntax higlighting definitions, and documentation:
Example 1. Files composing the vcscommand addon
syntax/vcscommit.vim syntax/SVNAnnotate.vim syntax/CVSAnnotate.vim plugin/vcssvn.vim plugin/vcscvs.vim plugin/vcscommand.vim doc/vcscommand.txt
For an addon to work properly (and its plugins being automatically loaded by Vim) all its files should be installed under a directory which is a component of the Vim runtime path, in the appropriate subdirectories. In the example above, if /usr/share/vim/vim73/ is the chosen component and if vcscommand should be installed there, then SVNAnnotate.vim should be installed as /usr/share/vim/vim73/syntax/SVNAnnotate.vim, vcssvn.vim as /usr/share/vim/vim73/plugin/vcssvn.vim, and so on.
Addons should not be installed directly under a directory contained in the Vim runtime path. This is because addons can conflict with each other and also because automatically loading plugins takes time. Therefore users shall be given the freedom to choose which addons they want to have enabled and which they don't. The suggested directory where to install addons is /usr/share/vim/addons, but any other directory not in the Vim runtime path will do, as long as you install there a file tree with the appropriate sub-directories in place (syntax/, plugin/, ...).
Each non-trivial addon[1] should be packaged and distributed in Debian as a separate package. It is recommended that the package is named according to the naming convention vim-ADDON where ADDON is a name identifying the packaged addon. Trivial addons should be collected in suites of Vim addons and packaged as aggregated Debian packages. An example of such a suite is distributed as the vim-script package.
To ease management of addons (e.g. enabling and disabling them) by both the final users and the local system administrators, each packaged addon should be registered in the Vim addon registry. The registry is (conceptually) a set of entries, one entry per addon, describing the addon from the point of view of who should configure it: its name and brief description, where it is located on disk, ... All such information should be easily findable in the upstream documentation of the addon.
Practically, each Debian package shipping Vim addons should provide a single file in YAML format describing all addons shipped by the package. The file should be installed by the package in /usr/share/vim/registry/ and should be named according to the convention PKGNAME.yaml, where PKGNAME is the name of the Debian package shipping it. There is no need to create the file in postinst, you can ship it normally as a file contained in your package.[2]
The following information should be made available for each addon registered in the addon registry:
short name of the addon, will be used to refer to the addon (also in command line tools, so beware of spaces, they can be annoying)
brief description of the addon, in the same spirit of Debian package short descriptions
list of files which compose the addon. Intuitively all these files should be made available in the appropriate components of the Vim runtime path for the addon to be working properly. Each file must be specified relative to a component of the Vim runtime path.
directory where the files composing the addon reside on the filesystem. This field is optional.
Vim script command that can be used (usually by adding it to ~/.vimrc) to prevent the addon to be used even when it is loaded. The intended usage of this field is to "blacklist" an undesired addon which files are available, and hence automatically loaded by Vim, in a component of the Vim runtime path. This field is optional, if missing the addon cannot be blacklisted.
Note the relevance of the disabledby field: having it is the only way for a user to prevent the automatic loading of an addon which has been installed system-wide by the local system administrator. If the addon you are packaging does not provide a way to be disabled you should patch it to support disabling and forward your patch upstream. Have a look at the Debian-specific patches in the vim-scripts package for an idea about how to do it.
A YAML file describing registry entries is a standard YAML file with multiple top-level entries (one per registry entry). All field mentioned above are singleton string fields with the exception of files which contains a list of strings (one for each shipped file). See the YAML file format specification for reference ... or the examples of Appendix A to learn by example.
You should not attempt to automatically enable the plugin in the postinst for the reasons mentioned above. It is recommended that enabling of addons should be delegated to the local system administrator and users. If you really feel the need to, please consider using debconf as a way to opt-out from the automatic enabling, and do that strictly using vim-addon-manager (see Section 4), so that users can blacklist the automatically loaded addon.
| [1] | meaning with "non-trivial" that its size justifies the creation of a Debian package for that, YMMV |
| [2] | In the future we might provide a debhelper to installed Vim registry files in the right place, but it is not available yet. |