r945 - /trunk/packages/vim/debian/policy/vim-policy.xml
zack at users.alioth.debian.org
zack at users.alioth.debian.org
Sun Jun 17 00:05:18 UTC 2007
Author: zack
Date: Sun Jun 17 00:05:15 2007
New Revision: 945
URL: http://svn.debian.org/wsvn/pkg-vim/?sc=1&rev=945
Log:
work in progress on the policy...
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=945&op=diff
==============================================================================
--- trunk/packages/vim/debian/policy/vim-policy.xml (original)
+++ trunk/packages/vim/debian/policy/vim-policy.xml Sun Jun 17 00:05:15 2007
@@ -4,7 +4,8 @@
<!ENTITY vim-version "7.1">
<!ENTITY vim-compat "1">
<!ENTITY vim-pkg "<application>vim</application>">
- <!ENTITY vim-name "<application>Vim</application>">
+ <!ENTITY vim "<application>Vim</application>">
+ <!ENTITY debian "Debian">
<!ENTITY authors SYSTEM "authors.xml">
<!ENTITY legal SYSTEM "legal.xml">
@@ -12,34 +13,147 @@
<article>
<articleinfo>
- <title>Debian Packaging Policy for &vim-name;</title>
+ <title>Debian Packaging Policy for &vim;</title>
<releaseinfo>Revision 0.0.1</releaseinfo>
&authors;
&legal;
</articleinfo>
<section id="legacy-packaging">
- <title>The &vim-name; Editor in Debian</title>
+ <title>The &vim; Editor in Debian</title>
- <para>
- foo
- </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>
+
</section>
<section id="addons-packaging">
- <title>Packaging of &vim-name; Addons</title>
+ <title>Packaging of &vim; Addons</title>
- <para>
- bar
- </para>
+ <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> <emphasis>TODO</emphasis> describe here what usually composes
+ an addon: i.e. stuff that should be put in various places in the
+ vim runtime path </para>
+
+ <para> <emphasis>TODO</emphasis> describe here how an addon should
+ be packages: i.e. as a directory tree isomorphic to what should
+ be put in a component of the vim runtime path, but located
+ *elsewhere* (so that it is not enabled per default) </para>
+
+ <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 a 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>
+
+ <para> The following information should be made available for each addon
+ registered in the addon registry: <variablelist>
+
+ <varlistentry> <term><emphasis>name</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 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> 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> <emphasis>TODO</emphasis> what to do in the postinst ...
+ </para>
+
+ <section id="registry-examples">
+ <title>&vim; Registry Entry Examples</title>
+
+ <para> <emphasis>TODO</emphasis> add some example of registry
+ entries </para>
+
+ </section>
+
</section>
<section id="tools">
<title>Tools</title>
- <para>
- baz
- </para>
+ <para> <emphasis>TODO</emphasis> brief mention of
+ <application>vim-addons</application> and what it does, pointing
+ to the manpage </para>
+
</section>
</article>
More information about the pkg-vim-maintainers
mailing list