r952 - /trunk/packages/vim/debian/policy/vim-policy.xml
zack at users.alioth.debian.org
zack at users.alioth.debian.org
Sun Jun 17 12:08:56 UTC 2007
Author: zack
Date: Sun Jun 17 12:08:56 2007
New Revision: 952
URL: http://svn.debian.org/wsvn/pkg-vim/?sc=1&rev=952
Log:
some more text...
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=952&op=diff
==============================================================================
--- trunk/packages/vim/debian/policy/vim-policy.xml (original)
+++ trunk/packages/vim/debian/policy/vim-policy.xml Sun Jun 17 12:08:56 2007
@@ -41,90 +41,165 @@
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>
+ <section id="addons-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
+ url="http://www.vim.org/scripts/script.php?script_id=90"><application>vcscommand</application></ulink>
+ addon, providing for 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. 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>,
+ <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>
+
+ </section>
+
+ <section>
+ <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 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>
+
+ </section>
+
+ <section>
+ <title>Registry Entries</title>
+
+ <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 (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://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim-scripts/debian/patches/?rev=0&sc=0">&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).
@@ -133,19 +208,13 @@
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!
+ <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>
@@ -158,4 +227,119 @@
</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>
More information about the pkg-vim-maintainers
mailing list