diff options
Diffstat (limited to 'debian/policy/vim-policy.xml')
| -rw-r--r-- | debian/policy/vim-policy.xml | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/debian/policy/vim-policy.xml b/debian/policy/vim-policy.xml new file mode 100644 index 0000000..03e1408 --- /dev/null +++ b/debian/policy/vim-policy.xml @@ -0,0 +1,228 @@ +<?xml version="1.0"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"/usr/share/sgml/docbook/dtd/xml/4.3/docbookx.dtd" [ + <!ENTITY vim-version "8.2"> + <!ENTITY vim "<application>Vim</application>"> + <!ENTITY debian "Debian"> + + <!ENTITY authors SYSTEM "authors.xml"> + <!ENTITY legal SYSTEM "legal.xml"> +]> + +<article> + <articleinfo> + <title>Debian Packaging Policy for &vim;</title> + <releaseinfo>Version 2.0</releaseinfo> + &authors; + &legal; + </articleinfo> + + <section id="nutshell"> + <title>&vim; Addon Packaging in a Nutshell</title> + + <warning> <para> This section contains a brief howto of what to do to + package a &vim; addon (plugin, syntax definition, ...) in &debian;. + This section is not the full policy nor the guidelines for doing that; + have a look at the remainder of this document for such information. + </para> </warning> + + <para> So you've found on <ulink url="https://www.vim.org">vim.org</ulink> a + cool extra feature for your beloved editor (&vim;) and you want it to be + packaged in &debian;. It's as easy as implementing the following 4 steps: + + <orderedlist numeration="arabic"> + + <listitem> <para> create an <code>architecture: all</code> + <filename>.deb</filename> binary package called + <application>vim-<replaceable>ADDON</replaceable></application>, + where <replaceable>ADDON</replaceable> is the addon name. See <xref + linkend="addon-packages" /> for more info on this. </para> + </listitem> + + <listitem> <para> make your package ship all the files composing your + addon (usually <filename>.vim</filename> and + <filename>.txt</filename> files) under + <filename>/usr/share/vim-<replaceable>ADDON</replaceable>/</filename>. The files should be + shipped as a file and directory tree isomorphic to what you want to + see in a runtime &vim; directory. So if for example the addon + documentation says that something should be installed as + <filename>plugin/foo.vim</filename> then you should ship it as + <filename>/usr/share/vim-<replaceable>ADDON</replaceable>/plugin/foo.vim</filename>. See <xref + linkend="addon-structure" /> for more info on this. </para> + </listitem> + + <listitem> <para>create a + <filename>debian/vim-<replaceable>ADDON</replaceable>.vim-addon</filename> + specifying the files and/or directories making up the addon. If neovim is also supported, create + a corresponding <filename>debian/vim-<replaceable>ADDON</replaceable>.neovim-addon</filename> + for it, or a symlink if the same set of files are used. + + See the <command>dh_vim-addon</command> manual page, in the <application>dh-vim-addon</application> + package, for more details. </para> </listitem> + + <listitem> <para>add <code>Depends: ${vim-addon:Depends}</code> to the binary package stanzas.</para> </listitem> + + </orderedlist> + + That's it! Easy, isn't it? </para> + + </section> + + <section id="legacy-packaging"> + <title>&vim; Packaging</title> + + <para> Here you can find a brief overview of how the &vim; editor is + packaged in &debian; and a few concepts useful later; if you are + just interested in the guidelines for packaging addons skip to + <xref linkend="addon-packaging" />. </para> + + <para> The &vim; editor is split in &debian; as several binary + packages. The key splitting is according to variants, a &vim; + <emphasis>variant</emphasis> is a particular version of the + <filename>/usr/bin/vim</filename> executable built with a given + set of (<application>configure</application>) option. Examples of + variants provided in &debian; are: <ulink + url="https://packages.debian.org/unstable/editors/vim-tiny"><application>vim-tiny</application></ulink>, + <ulink + url="https://packages.debian.org/unstable/editors/vim"><application>vim</application></ulink>, + <ulink + url="https://packages.debian.org/unstable/editors/vim-nox"><application>vim-nox</application></ulink>, + <ulink + url="https://packages.debian.org/unstable/editors/vim-gtk3"><application>vim-gtk3</application></ulink>. + Have a look at their full descriptions for their characteristics. + The actual <filename>/usr/bin/vim</filename> file is managed via + the alternative mechanism and point to one of the variants. + </para> + + <para> Another relevant binary package is <ulink + url="https://packages.debian.org/unstable/editors/vim-runtime"><application>vim-runtime</application></ulink> + which ships the &vim; runtime environment distributed upstream together + with the editor. Almost all third party extensions to &vim; come as + additional pieces of this runtime environment, how to package them is the + main topic of this document. </para> + + <para> To be working properly extensions should be located somewhere where + &vim; can find them. This "somewhere" is expressed in &vim; as a list of + directories to be looked for in turn when looking for extensions. Such a + list is the <emphasis>&vim; runtime path</emphasis>, and is kept in the + &vim; global variable <envar>runtimepath</envar>; you can inspect it + executing <command>:set runtimepath?</command> inside &vim;. See <ulink + url="https://vimhelp.org/options.txt.html#'runtimepath'"><command>:help + 'runtimepath'</command></ulink> in the &vim; online help for more + information, including the relevant subdirectories which &vim; will look + for inside <emphasis>each</emphasis> component of the runtime path. + </para> + + <para> &vim; also has a concept of <emphasis>packages</emphasis>. A package + must follow a specific directory structure and be located in one of the + directories defined in the <envar>packpath</envar> option. Within each + package, there are two relevant directories: <variablelist> + + <varlistentry><term><emphasis>start</emphasis></term> + <listitem><para>All addons in this directory will automatically + be added to <envar>runtimepath</envar> and loaded like any other + addon that comes with &vim;. These are called + <emphasis>automatic</emphasis> addons.</para> </listitem> </varlistentry> + + <varlistentry><term><emphasis>opt</emphasis></term> + <listitem><para>Any addons in this directory must explicitly + be enabled by executing <command>:packadd! <replaceable>ADDON</replaceable></command> + in the user's vimrc. These are called <emphasis>optional</emphasis> addons. + </para> </listitem> </varlistentry> + </variablelist> </para> + </section> + + <section id="addon-packaging"> + <title>Packaging of &vim; Addons</title> + + <para> With the term (&vim;) <emphasis>addon</emphasis> 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, ... </para> + + <section id="addon-structure"> + <title>Addon Structure</title> + + <para> An addon is usually composed of a set of <filename>.vim</filename> + files; other kind of files, for example <filename>.txt</filename> files + for documentation purposes, can be provided as well. + + For instance, the following files compose the <ulink + url="https://www.vim.org/scripts/script.php?script_id=90"><application>vcscommand</application></ulink> + addon, providing plugins, syntax higlighting definitions, and + documentation: + + <example> <title>Files composing the + <application>vcscommand</application> addon</title> + <programlisting>doc/tags +doc/vcscommand.txt +plugin/vcsbzr.vim +plugin/vcscommand.vim +plugin/vcscvs.vim +plugin/vcsgit.vim +plugin/vcshg.vim +plugin/vcssvk.vim +plugin/vcssvn.vim +syntax/cvsannotate.vim +syntax/gitannotate.vim +syntax/hgannotate.vim +syntax/svkannotate.vim +syntax/svnannotate.vim +syntax/vcscommit.vim</programlisting> + </example> + + </para> + + <para> For an addon to work properly (and its plugins being automatically + loaded by &vim;) all its files should be installed under a unique directory + which will be added to &vim;'s pack path. In the example above, if + <filename>/usr/share/vim-vcscommand/</filename> is the chosen directory, + then <filename>SVNAnnotate.vim</filename> should be installed as + <filename>/usr/share/vim-vcscommand/syntax/SVNAnnotate.vim</filename>, + <filename>vcssvn.vim</filename> as + <filename>/usr/share/vim-vcscommand/plugin/vcssvn.vim</filename>, and so + on. </para> + + </section> + + <section id="addon-packages"> + <title>Addon Packages</title> + + <para> Each addon should be packaged and distributed in &debian; + as a separate package. It is recommended that the package is + named according to the naming convention + <application>vim-<replaceable>ADDON</replaceable> </application> + where <replaceable>ADDON</replaceable> is a name identifying the + packaged addon. </para> + + <para> Each binary package should contain a single addon installed as an + <emphasis>automatic</emphasis> addon. If the addon requires + heavy customization or is noticeably intrusive, it may be preferable + to install it as an <emphasis>optional</emphasis> addon.</para> + + <para> In some cases, it may make sense to aggregate multiple &vim; addons in + a single &debian; package. An example of such a suite is distributed as + the <ulink url="https://packages.qa.debian.org/vim-scripts"> + <application>vim-scripts</application> package</ulink>. + + In such cases, the addons should be installed as <emphasis>optional</emphasis> + addons so the user can choose which ones to enable. </para> + + </section> + </section> + + <section id="tools"> + <title>Tools</title> + + <para> <command>dh_vim-addons</command> is the tool used by maintainers + to install &vim; addons into the appropriate runtime path. It is shipped in the <ulink + url="https://packages.qa.debian.org/dh-vim-addon"><application>dh-vim-addon</application></ulink> + package. It will ensure that the addons are installed in to the correct + <envar>packpath</envar>, based on whether it is an <emphasis>automatic</emphasis> + or <emphasis>optional</emphasis> addon, and which editors are supported. </para> + + </section> + +</article> |