r956 - /trunk/packages/vim/debian/policy/vim-policy.xml
zack at users.alioth.debian.org
zack at users.alioth.debian.org
Mon Jun 18 20:59:44 UTC 2007
Author: zack
Date: Mon Jun 18 20:59:43 2007
New Revision: 956
URL: http://svn.debian.org/wsvn/pkg-vim/?sc=1&rev=956
Log:
completed the first draft of the VIM policy (yay!)
Modified:
trunk/packages/vim/debian/policy/vim-policy.xml
Modified: trunk/packages/vim/debian/policy/vim-policy.xml
URL: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim/debian/policy/vim-policy.xml?rev=956&op=diff
==============================================================================
--- trunk/packages/vim/debian/policy/vim-policy.xml (original)
+++ trunk/packages/vim/debian/policy/vim-policy.xml Mon Jun 18 20:59:43 2007
@@ -2,6 +2,7 @@
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"/usr/share/sgml/docbook/dtd/xml/4.3/docbookx.dtd" [
<!ENTITY vim-version "7.1">
+ <!ENTITY vim-tag "vim71">
<!ENTITY vim-compat "1">
<!ENTITY svn-id "$Id$">
<!ENTITY svn-rev "$Rev$">
@@ -16,7 +17,7 @@
<article>
<articleinfo>
<title>Debian Packaging Policy for &vim;</title>
- <releaseinfo>Version 0.1.0 (&svn-rev;)</releaseinfo>
+ <releaseinfo>Version 0.0.1 (&svn-rev;)</releaseinfo>
&authors;
&legal;
</articleinfo>
@@ -32,18 +33,18 @@
<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
- packages in &debian;. It's as easy as implementing the followin 4 steps:
+ packaged in &debian;. It's as easy as implementing the following 4 steps:
<orderedlist numeration="arabic">
- <listitem> <para> create a <code>architecture: all</code>
+ <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> makes your package ship all the files composing your
+ <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
@@ -118,41 +119,45 @@
<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. </para>
-
- <para> TODO FINQUI </para>
-
- <para> <emphasis>TODO</emphasis> brief description of &vim; packaging in
- &debian;, salient info like what is the runtime path and how &vim; has
- been split in packages </para>
+ 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 will
- refer to an additional feature for the &vim; editor which is not
- shipped with the editor itself. Examples of addons which can be
- frequently found on the net are color schemes, syntax and
- corresponding higlighting definitions for new languages,
- indentation definitions, generic and filetype-specific plugins,
- ... </para>
+ <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 which should be installed
- somewhere under a directory which is a component of the &vim;
- runtime path. Other kind of files, for example
- <filename>.txt</filename> files for documentation purposes, can
- be provided as well.
-
- For example, the following files compose the <ulink
+ <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 for plugins, syntax higlighting definitions, and
+ addon, providing plugins, syntax higlighting definitions, and
documentation:
<example> <title>Files composing the
@@ -168,32 +173,29 @@
</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. Sub-directories of the component should be used
- respecting the paths above. In the example above, if
- <filename>/usr/share/vim/vim71/</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/vim71/syntax/SVNAnnotate.vim</filename>,
+ <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/vim71/plugin/vcssvn.vim</filename> and
- so on. </para>
-
- <para> In &debian; it is required that 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>
+ <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>
@@ -310,7 +312,14 @@
<xref linkend="registry-examples" /> to learn by example.
</para>
- <para> <emphasis>TODO</emphasis> what to do in the postinst ... (nothing!)
+ <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>
@@ -320,12 +329,28 @@
<section id="tools">
<title>Tools</title>
- <para> <emphasis>TODO</emphasis> brief mention of
- <application>vim-addons</application> and what it does, pointing
- to the manpage </para>
-
- <para> <emphasis>TODO</emphasis> mention the needed Recommend:
- vim-addon-manager </para>
+ <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>
More information about the pkg-vim-maintainers
mailing list