Source

vim / debian / policy / vim-policy.xml

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
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.1">
  <!ENTITY vim-tag "vim71">
  <!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 enable 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 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 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>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://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>