Adding debian version 2:8.1.0875-5+deb10u2.debian/2%8.1.0875-5+deb10u2debian

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 470 insertions, 0 deletions

diff --git a/debian/policy/vim-policy.xml b/debian/policy/vim-policy.xml
new file mode 100644
index 0000000..a28b317
--- /dev/null
+++ b/debian/policy/vim-policy.xml
@@ -0,0 +1,470 @@
+<?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 "7.3">
+  <!ENTITY vim-tag "vim73">
+  <!ENTITY vim-compat  "1">
+  <!ENTITY vim-pkg "<application>vim</application>">
+  <!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 1.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="http://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/addons/</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/addons/plugin/foo.vim</filename>. See <xref
+	      linkend="addon-structure" /> for more info on this. </para>
+	</listitem>
+
+	<listitem> <para>create a
+	    <filename>vim-<replaceable>ADDON</replaceable>.yaml</filename>
+	    registry file for your addon and ship it as
+	    <filename>/usr/share/vim/registry/vim-<replaceable>ADDON</replaceable>.yaml</filename>.
+	    You can find documentation on how to write a registry file in <xref
+	      linkend="registry-entry" /> and cut&amp;paste-ready examples in
+	    <xref linkend="registry-examples" />.  If the addon you are
+	    packaging does not provide a way to disable it consider patching it
+	    so that it is possible, put in your registry entry the appropriate
+	    <emphasis>disabledby</emphasis> field, and forward the patch
+	    upstream. </para> </listitem>
+
+	<listitem> <para> <code>Recommend: vim-addon-manager</code> in your
+	    <filename>debian/control</filename> and write into
+	    <filename>README.Debian</filename> something like: <blockquote>
+	      <para> Dear user, this package provides the vim addon
+		<replaceable>ADDON</replaceable>, but it is not enabled per
+		default. If you want to enable it for your user account just
+		execute <userinput>vim-addons install
+		  <replaceable>ADDON</replaceable></userinput>. Similarly, to
+		enable it for all users of this system just execute (as root)
+		<userinput>vim-addons -w install
+		  <replaceable>ADDON</replaceable></userinput>.
+		<command>vim-addons</command> is provided by the
+		<application>vim-addon-manager</application> package, have a
+		look at its manpage for more information. </para> </blockquote>
+	    See <xref linkend="tools" /> for more info on this.  </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="http://packages.debian.org/unstable/editors/vim-tiny"><application>vim-tiny</application></ulink>,
+      <ulink
+	url="http://packages.debian.org/unstable/editors/vim"><application>vim</application></ulink>,
+      <ulink
+	url="http://packages.debian.org/unstable/editors/vim-nox"><application>vim-nox</application></ulink>,
+      <ulink
+	url="http://packages.debian.org/unstable/editors/vim-gtk"><application>vim-gtk</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="http://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="http://vimdoc.sourceforge.net/htmldoc/options.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>
+
+  </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="http://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>syntax/vcscommit.vim
+syntax/SVNAnnotate.vim
+syntax/CVSAnnotate.vim
+plugin/vcssvn.vim
+plugin/vcscvs.vim
+plugin/vcscommand.vim
+doc/vcscommand.txt</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 directory
+	which is a component of the &vim; runtime path, in the appropriate
+	subdirectories. In the example above, if
+	<filename>/usr/share/vim/&vim-tag;/</filename> is the chosen component
+	and if <application>vcscommand</application> should be installed there,
+	then <filename>SVNAnnotate.vim</filename> should be installed as
+	<filename>/usr/share/vim/&vim-tag;/syntax/SVNAnnotate.vim</filename>,
+	<filename>vcssvn.vim</filename> as
+	<filename>/usr/share/vim/&vim-tag;/plugin/vcssvn.vim</filename>, and so
+	on. </para>
+
+      <para> Addons should <emphasis>not</emphasis> 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
+	<filename>/usr/share/vim/addons</filename>, 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
+	(<filename>syntax/</filename>, <filename>plugin/</filename>, ...).
+      </para>
+
+    </section>
+
+    <section id="addon-packages">
+      <title>Addon Packages</title>
+
+      <para> Each non-trivial addon<footnote> <para> meaning with
+	    "non-trivial" that its size justifies the creation of a
+	    &debian; package for that, YMMV </para> </footnote> 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. 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 <ulink
+	  url="http://packages.qa.debian.org/vim-scripts">
+	  <application>vim-script</application> package</ulink>. </para>
+
+      <para> 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
+	<emphasis>&vim; addon registry</emphasis>. 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. </para>
+
+      <para> Practically, each &debian; package shipping &vim; addons
+	should provide a single file in <ulink
+	  url="http://www.yaml.org">YAML</ulink> format describing
+	<emphasis>all</emphasis> addons shipped by the package.  The
+	file should be installed by the package in
+	<filename>/usr/share/vim/registry/</filename> and should be
+	named according to the convention
+	<filename><replaceable>PKGNAME</replaceable>.yaml</filename>,
+	where <replaceable>PKGNAME</replaceable> 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.<footnote> <para> In the future we might
+	    provide a debhelper to installed &vim; registry files in the
+	    right place, but it is not available yet.  </para>
+      </footnote> </para>
+
+    </section>
+
+    <section id="registry-entry">
+      <title>Registry Entries</title>
+
+      <para> The following information should be made available for each
+	addon registered in the addon registry: <variablelist>
+
+	  <varlistentry> <term><emphasis>addon</emphasis> (required
+	      field)</term> <listitem> <para>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)
+	      </para> </listitem> </varlistentry>
+
+	  <varlistentry> <term><emphasis>description</emphasis>
+	      (required field)</term> <listitem> <para>brief description
+		of the addon, in the same spirit of &debian; package
+		short descriptions</para> </listitem> </varlistentry>
+
+	  <varlistentry> <term><emphasis>files</emphasis> (required
+	      field)</term> <listitem> <para> 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. </para> </listitem>
+	  </varlistentry>
+
+	  <varlistentry> <term><emphasis>basedir</emphasis> (optional
+	      field, default:
+	      <filename>/usr/share/vim/addons</filename>) </term>
+	    <listitem> <para> directory where the files composing the
+		addon reside on the filesystem. This field is optional.
+	  </para> </listitem> </varlistentry>
+
+	  <varlistentry>  <term><emphasis>disabledby</emphasis>
+	      (optional field)</term> <listitem> <para> &vim; script
+		command that can be used (usually by adding it to
+		<filename>~/.vimrc</filename>) 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.  </para> </listitem> </varlistentry>
+
+      </variablelist> </para>
+
+      <para> Note the relevance of the <emphasis>disabledby</emphasis>
+	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 <ulink
+	  url="http://git.debian.org/?p=pkg-vim/vim-scripts.git;a=tree;f=debian/patches;hb=HEAD">&debian;-specific
+	  patches</ulink> in the <ulink
+	  url="http://packages.qa.debian.org/vim-scripts"><application>vim-scripts</application></ulink>
+	package for an idea about how to do it. </para>
+
+      <para> 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 <emphasis>files</emphasis> which contains a list of
+	strings (one for each shipped file). See the <ulink
+	  url="http://yaml.org/spec/">YAML file format
+	  specification</ulink> for reference ... or the examples of
+	<xref linkend="registry-examples" /> to learn by example.
+      </para>
+
+      <para> 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 <ulink
+	  url="http://packages.qa.debian.org/debconf">debconf</ulink> as a way
+	to opt-out from the automatic enabling, and do that strictly using
+	<application>vim-addon-manager</application> (see <xref linkend="tools"
+	  />), so that users can blacklist the automatically loaded addon.
+      </para>
+
+    </section>
+
+  </section>
+
+  <section id="tools">
+    <title>Tools</title>
+
+    <para> <command>vim-addons</command> is the tool used by users and local
+      administrator to manage &vim; addons. It is shipped in the <ulink
+	url="http://packages.qa.debian.org/vim-addon-manager"><application>vim-addon-manager</application></ulink>
+      package. Using it the <emphasis>state</emphasis> of an addon can be
+      changed to one of <emphasis>installed</emphasis>,
+      <emphasis>removed</emphasis>, <emphasis>disabled</emphasis> (i.e.
+      prevented to be loaded even if available somewhere in the &vim; runtime
+      path). The state of each addon can be changed both for a single user
+      (playing with symbolic links in <filename>~/.vim</filename>) and for all
+      system users (via <filename>/var/lib/vim/addons/</filename>, which is
+      contained in the &vim; runtime path).  </para>
+
+    <para> For more information about <command>vim-addons</command> see its
+      manpage: <code>vim-addons(1)</code>. </para>
+
+    <para> Since <command>vim-addons</command> is the recommended way of
+      managing &vim; addons available in a &debian; system, you should instruct
+      your package users about it. You should hence put a <code>Recommend:
+	vim-addon-manager</code> to your addon package and provide a suitable
+      <filename>README.Debian</filename> with basic instructions about how to
+      use it. See <xref linkend="nutshell" /> for a template where to start
+      from. </para>
+
+  </section>
+
+  <appendix id="registry-examples">
+    <title>&vim; Registry Entry Examples</title>
+    
+    <para> Here you can find several examples of YAML files containing
+      entries for the &vim; addon registry. </para>
+
+    <example>
+      <title><filename>vim-runtime.yaml</filename>: entry for the
+	matchit plugin</title>
+
+      <para>The <application>vim-runtime</application> package
+	itself ships an addon: the matchit plugin. It is rather
+	standard as it ships its content under
+	<filename>/usr/share/vim/addons</filename> and has no way to
+	be prevented from being loaded. The content of
+	<filename>/usr/share/vim/registry/vim-runtime.yaml</filename>
+	follows.</para>
+
+      <programlisting>addon: matchit
+description: extended matching with "%" (e.g. if ... then ... else)
+files:
+  - plugin/matchit.vim
+  - doc/matchit.txt</programlisting>
+
+    </example>
+
+    <example>
+      <title><filename>vim-scripts.yaml</filename>: entries for the
+	&vim; scripts addon suite</title>
+
+      <para>The <application>vim-scripts</application> package ships a
+	suite of several addons, for each shipped addon an entry for the
+	addon registry is provided. Since the shipped addons are not
+	installed in the default addon directories the
+	<emphasis>basedir</emphasis> field should be specified.  Several
+	addons provide a way for being blacklisted, for example the
+	<application>alternatve</application> addon can be disabled by
+	adding the line <command>let loaded_alternateFile = 1</command>
+	somewhere in <filename>~/.vimrc</filename>.  (Part of) the
+	content of
+	<filename>/usr/share/vim/registry/vim-scripts.yaml</filename>
+	follows.</para>
+
+      <programlisting>addon: alternate
+description: "alternate pairing files (e.g. .c/.h) with short ex-commands"
+basedir: /usr/share/vim-scripts/
+disabledby: "let loaded_alternateFile = 1"
+files:
+  - plugin/a.vim
+  - doc/alternate.txt
+---
+addon: gnupg
+description: "transparent editing of gpg encrypted files"
+basedir: /usr/share/vim-scripts/
+disabledby: "let loaded_gnupg = 1"
+files:
+  - plugin/gnupg.vim
+---
+addon: align
+description: "commands and maps for aligned text, equations, declarations, ..."
+basedir: /usr/share/vim-scripts/
+disabledby: "let loaded_alignPlugin = 1"
+files:
+  - plugin/AlignPlugin.vim
+  - doc/Align.txt
+  - plugin/AlignMaps.vim
+  - plugin/cecutil.vim
+  - autoload/Align.vim
+---
+addon: themes
+description: "colors sampler pack: all the color schemes on vim.sf.net"
+basedir: /usr/share/vim-scripts/
+disabledby: "let loaded_themes = 1"
+files:
+  - plugin/themes.vim
+  - colors/adam.vim
+  - colors/adaryn.vim
+<emphasis># long list snipped here</emphasis></programlisting>
+
+    </example>
+
+    <example> <title><filename>vim-latexsuite.yaml</filename>: entries
+	for the &vim; LaTeX suite</title>
+
+      <para>The <application>vim-latexsuite</application> contains
+	several advanced features for editing LaTeX documents with
+	&vim;. (Part of) the content of
+	<filename>/usr/share/vim/registry/vim-latexsuite.yaml</filename>
+	follows.</para>
+
+      <programlisting>addon: latex-suite
+description: "comprehensive set of tools to view, edit, and compile LaTeX documents"
+disabledby: "let did_latexSuite_disabled = 1"
+files:
+  - compiler/tex.vim
+  - doc/imaps.txt.gz
+  - doc/latexhelp.txt.gz
+  - doc/latex-suite-quickstart.txt.gz
+  - doc/latex-suite.txt.gz
+  - ftplugin/bib_latexSuite.vim
+  - ftplugin/latex-suite/bibtex.vim
+  <emphasis># loooong file listing snipped here</emphasis>
+  - ftplugin/tex_latexSuite.vim
+  - ftplugin/tex/texviewer.vim
+  - indent/tex.vim
+  - plugin/filebrowser.vim
+  - plugin/imaps.vim
+  - plugin/libList.vim
+  - plugin/remoteOpen.vim
+  - plugin/SyntaxFolds.vim</programlisting>
+
+    </example>
+
+  </appendix>
+
+</article>