$Id: vim-policy.txt,v 1.2 2003/10/11 19:42:39 arturcz Exp $
$Source: /var/lib/cvs/vsp/vim-policy.txt,v $

Debian Vim Scripts Policy

Abstract

This document describes the packaging of Vim scripts within the Debian
GNU/Linux distribution and the policy requirements for such packages.

Copyright  2003 Artur R. Czechowski, Jakub Turski

This manual is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

A copy of the GNU General Public License is available as
/usr/share/common-licenses/GPL in the Debian GNU/Linux
distribution or on the World Wide Web at http://www.gnu.org/copyleft/gpl.html

You can also obtain it by writing to the Free Software Foundation, Inc., 59
Temple Place - Suite 330, Boston, MA 02111-1307, USA.



1. Separation of additional scripts

All scripts introduced by other packages should be installed under
/usr/share/vim/addons/ directory. This directory should be present in
'runtimepath' setting of vim. We recommend either setting it in global vimrc or
(better) compiling it in (if such solution is possible). New runtimepath should
look like this:

  runtimepath=~/.vim,/etc/vim,/usr/share/vim/vimfiles,/usr/share/vim/addons,/usr/share/vim/vim62,/usr/share/vim/vimfiles/after,~/.vim/after

This separation is proposed in order to get rid of versioning problem. Right
now, scripts should go in /usr/share/vim/vimXY dir, which can change with vim
package version.

Note that new directory is added before standard directory, in order for
scripts files to take precedency.



2. Vim startup.

Vim should automatically source all scripts added into /usr/share/vim/addons.
We believe that IF site administrator is installing a script system-wide, from
a package, THEN this script is considered important and is meant to be sourced
automatically. Therefore, administrators should think twice before installing
a script in this way. 

If the particular user does not share this point of view, he has the option to
change this behaviour, by removing /usr/share/vim/addons from the runtimepath.
It can be accomplished by setting runtimepath in his or her ~/.vimrc.

If the user has removed /usr/share/vim/addons from runtimepath, but still wants
to user *some* of scripts installed there, he can use vim-install utility,
which will help in creating set of symlinks, from user's ~/.vim/ directory to
adequate files in /usr/share/vim/addons directory. This utility is available
here:

http://yacoob.dnsalias.net/sakwa/vim-install

It should be included into vim package.



3. Dependencies.

The script package should depend on vim package. It may also specify version
number if such dependency is needed. If package contains script with
documentation, it should pre-depend on vim package.



4. Help files handling and helptags generation.

All scripts documentation should be put in compressed form in
/usr/share/vim/addons/doc directory. A script that will generate helptags file
for this directory has been written and is available at:

http://yacoob.dnsalias.net/sakwa/helpztags

It should be included into vim package. All packages containing vim scripts
with documentation should pre-depend on vim.



5. Naming.

All packages that contain vim scripts and adhere to this policy must be named
in following pattern:
 vim-script-name

Currently, only vim-latexsuite conforms to this point.



6. Conflict resolving.

There are two possible cases:

If package introduces the same file as in standard vim distribution, the
package version takes precedence. It is put in /usr/share/vim/addons/ directory
which appears before standard vim dir.

If package introduces the same file as another package with another vim
scripts, both packages should use update-alternatives in order to solve this
conflict. Priority should be calculated as follows:

  * Start with a priority of 20.
  * If package allows user customization, add 10.
  * Judge about amount of provided features.



7. vim-scripts package.

This package is intended to act as a 'bag of scripts'. Scripts in this package
are NOT put into /usr/share/vim/addons/, and thus are NOT enabled by default.
If user (or administrator) wants to enable one of the scripts from vim-scripts
package, he should copy it to specific directory (i.e. ~/.vim/).

If you are going to package a script with conformance to this policy, please
check if it is included in vim-scripts package. If it is, please inform the
vim-scripts package maintainer that he should remove this scipt from
vim-scripts package.

Please also note, that most of 'one-file' scripts should rather remain in
vim-scripts than be packaged in their own package. Candidates for separate
packages are set of scripts (like latexSuite) or scripts that introduce some
sort of infrastructure (perl-support, with templates and dictionary file) or
simply scripts that consist of more than one vim file.

==============================================================================

This policy is open for discussion!
Authors can be reached at:
Artur R. Czechowski <arturcz at hell dot pl>
Jakub Turski <yacoob at chruptak dot plukwa dot net>
