From 0cde7a370d07f80208bcd29597cf30d5274f38b0 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 04:44:26 +0200 Subject: Adding debian version 2:8.1.0875-5+deb10u2. Signed-off-by: Daniel Baumann --- debian/policy/vim-policy.xml | 470 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 470 insertions(+) create mode 100644 debian/policy/vim-policy.xml (limited to 'debian/policy/vim-policy.xml') 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 @@ + + + + + vim"> + Vim"> + + + + +]> + +
+ + Debian Packaging Policy for &vim; + Version 1.0 + &authors; + &legal; + + +
+ &vim; Addon Packaging in a Nutshell + + 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. + + + So you've found on vim.org 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: + + + + create an architecture: all + .deb binary package called + vim-ADDON, + where ADDON is the addon name. See for more info on this. + + + make your package ship all the files composing your + addon (usually .vim and + .txt files) under + /usr/share/vim/addons/. 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 + plugin/foo.vim then you should ship it as + /usr/share/vim/addons/plugin/foo.vim. See for more info on this. + + + create a + vim-ADDON.yaml + registry file for your addon and ship it as + /usr/share/vim/registry/vim-ADDON.yaml. + You can find documentation on how to write a registry file in and cut&paste-ready examples in + . 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 + disabledby field, and forward the patch + upstream. + + Recommend: vim-addon-manager in your + debian/control and write into + README.Debian something like:
+ Dear user, this package provides the vim addon + ADDON, but it is not enabled per + default. If you want to enable it for your user account just + execute vim-addons install + ADDON. Similarly, to + enable it for all users of this system just execute (as root) + vim-addons -w install + ADDON. + vim-addons is provided by the + vim-addon-manager package, have a + look at its manpage for more information.
+ See for more info on this. + + + + + That's it! Easy, isn't it? + +
+ +
+ &vim; Packaging + + 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 + . + + The &vim; editor is split in &debian; as several binary + packages. The key splitting is according to variants, a &vim; + variant is a particular version of the + /usr/bin/vim executable built with a given + set of (configure) option. Examples of + variants provided in &debian; are: vim-tiny, + vim, + vim-nox, + vim-gtk. + Have a look at their full descriptions for their characteristics. + The actual /usr/bin/vim file is managed via + the alternative mechanism and point to one of the variants. + + + Another relevant binary package is vim-runtime + 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. + + 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 &vim; runtime path, and is kept in the + &vim; global variable runtimepath; you can inspect it + executing :set runtimepath inside &vim;. See :help + 'runtimepath' in the &vim; online help for more + information, including the relevant subdirectories which &vim; will look + for inside each component of the runtime path. + + +
+ +
+ Packaging of &vim; Addons + + With the term (&vim;) addon 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, ... + +
+ Addon Structure + + An addon is usually composed of a set of .vim + files; other kind of files, for example .txt files + for documentation purposes, can be provided as well. + + For instance, the following files compose the vcscommand + addon, providing plugins, syntax higlighting definitions, and + documentation: + + Files composing the + <application>vcscommand</application> addon + syntax/vcscommit.vim +syntax/SVNAnnotate.vim +syntax/CVSAnnotate.vim +plugin/vcssvn.vim +plugin/vcscvs.vim +plugin/vcscommand.vim +doc/vcscommand.txt + + + + + 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 + /usr/share/vim/&vim-tag;/ is the chosen component + and if vcscommand should be installed there, + then SVNAnnotate.vim should be installed as + /usr/share/vim/&vim-tag;/syntax/SVNAnnotate.vim, + vcssvn.vim as + /usr/share/vim/&vim-tag;/plugin/vcssvn.vim, and so + on. + + Addons should not 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 + /usr/share/vim/addons, 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 + (syntax/, plugin/, ...). + + +
+ +
+ Addon Packages + + Each non-trivial addon meaning with + "non-trivial" that its size justifies the creation of a + &debian; package for that, YMMV should + be packaged and distributed in &debian; as a separate package. + It is recommended that the package is named according to the + naming convention + vim-ADDON + where ADDON 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 + vim-script package. + + 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 + &vim; addon registry. 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. + + Practically, each &debian; package shipping &vim; addons + should provide a single file in YAML format describing + all addons shipped by the package. The + file should be installed by the package in + /usr/share/vim/registry/ and should be + named according to the convention + PKGNAME.yaml, + where PKGNAME 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. In the future we might + provide a debhelper to installed &vim; registry files in the + right place, but it is not available yet. + + +
+ +
+ Registry Entries + + The following information should be made available for each + addon registered in the addon registry: + + addon (required + field) 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) + + + description + (required field) brief description + of the addon, in the same spirit of &debian; package + short descriptions + + files (required + field) 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. + + + basedir (optional + field, default: + /usr/share/vim/addons) + directory where the files composing the + addon reside on the filesystem. This field is optional. + + + disabledby + (optional field) &vim; script + command that can be used (usually by adding it to + ~/.vimrc) 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. + + + + Note the relevance of the disabledby + 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 &debian;-specific + patches in the vim-scripts + package for an idea about how to do it. + + 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 files which contains a list of + strings (one for each shipped file). See the YAML file format + specification for reference ... or the examples of + to learn by example. + + + 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 debconf as a way + to opt-out from the automatic enabling, and do that strictly using + vim-addon-manager (see ), so that users can blacklist the automatically loaded addon. + + +
+ +
+ +
+ Tools + + vim-addons is the tool used by users and local + administrator to manage &vim; addons. It is shipped in the vim-addon-manager + package. Using it the state of an addon can be + changed to one of installed, + removed, disabled (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 ~/.vim) and for all + system users (via /var/lib/vim/addons/, which is + contained in the &vim; runtime path). + + For more information about vim-addons see its + manpage: vim-addons(1). + + Since vim-addons 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 Recommend: + vim-addon-manager to your addon package and provide a suitable + README.Debian with basic instructions about how to + use it. See for a template where to start + from. + +
+ + + &vim; Registry Entry Examples + + Here you can find several examples of YAML files containing + entries for the &vim; addon registry. + + + <filename>vim-runtime.yaml</filename>: entry for the + matchit plugin + + The vim-runtime package + itself ships an addon: the matchit plugin. It is rather + standard as it ships its content under + /usr/share/vim/addons and has no way to + be prevented from being loaded. The content of + /usr/share/vim/registry/vim-runtime.yaml + follows. + + addon: matchit +description: extended matching with "%" (e.g. if ... then ... else) +files: + - plugin/matchit.vim + - doc/matchit.txt + + + + + <filename>vim-scripts.yaml</filename>: entries for the + &vim; scripts addon suite + + The vim-scripts 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 + basedir field should be specified. Several + addons provide a way for being blacklisted, for example the + alternatve addon can be disabled by + adding the line let loaded_alternateFile = 1 + somewhere in ~/.vimrc. (Part of) the + content of + /usr/share/vim/registry/vim-scripts.yaml + follows. + + 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 +# long list snipped here + + + + <filename>vim-latexsuite.yaml</filename>: entries + for the &vim; LaTeX suite + + The vim-latexsuite contains + several advanced features for editing LaTeX documents with + &vim;. (Part of) the content of + /usr/share/vim/registry/vim-latexsuite.yaml + follows. + + 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 + # loooong file listing snipped here + - 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 + + + + + +
-- cgit v1.2.3