[yacoob@hell.pl: vim policy]

Norbert Tretkowski tretkowski@inittab.de
Sun, 5 Jun 2005 23:43:34 +0200


--dDRMvlgZJXvWKvBx
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Uh... I completely forgot about this mail...

Norbert

--dDRMvlgZJXvWKvBx
Content-Type: message/rfc822
Content-Disposition: inline
Content-Transfer-Encoding: 7bit

Return-Path: <yacoob@hell.pl>
X-Original-To: tretkowski@inittab.de
Delivered-To: tretkowski@mail1.inittab.de
X-Greylist: delayed 645 seconds by postgrey-1.18 at infinity; Tue, 12 Apr 2005 19:49:42 CEST
Received: from magi.nerv.pl (ava159.neoplus.adsl.tpnet.pl [83.27.34.159])
	by mail1.inittab.de (Postfix) with ESMTP id 41AB3C37F5
	for <tretkowski@inittab.de>; Tue, 12 Apr 2005 19:49:42 +0200 (CEST)
Received: from yacoob by magi.nerv.pl with local (masqmail 0.2.20) id
 1DLPM0-2oS-00; Tue, 12 Apr 2005 19:39:12 +0200
Date: Tue, 12 Apr 2005 19:39:12 +0200
From: Jakub Turski <yacoob@hell.pl>
To: tretkowski@inittab.de
Cc: arturcz@hell.pl
Subject: vim policy
Message-ID: <20050412173912.GA10716@dfs>
Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="ReaqsoxgOBHFXBhH"
Content-Disposition: inline
Organization: Me? Organized? Get serious...
X-Geek-Code-1: GCS/IT d-(--) s++:+ a-->? C++(+++)$ UL++++$ P+>++++$ L+++$>++++
X-Geek-Code-2: E--- W+@ N* o+ K- w--(---)$ O- M- V? !PS PE Y+
X-Geek-Code-3: PGP++ t+(++) 5 X R* tv-- b++++ DI++ D G++ e+>+++++>$ h!>++ r++ y?
X-PubKey-Fingerprint: 0ECD 2DA8 CE7F 18F8 2798  BBED 421C 0616 2277 5246
User-Agent: Mutt/1.5.8i
X-Spam-Checker-Version: SpamAssassin 3.0.2 (2004-11-16) on infinity.inittab.de
X-Spam-Level: 
X-Spam-Status: No, score=-0.5 required=4.0 tests=BAYES_00,RCVD_IN_NJABL_DUL,
	RCVD_IN_SORBS_DUL,RCVD_IN_SORBS_WEB autolearn=no version=3.0.2
X-Bogosity: Unsure, tests=bogofilter, spamicity=0.500000, version=0.94.3
Content-Transfer-Encoding: 7bit


--ReaqsoxgOBHFXBhH
Content-Type: text/plain; charset=iso-8859-2
Content-Disposition: inline

Hi,

 Some time ago (a year? or so) together with Artur Czechowski we've created
 a proposal for Vim Scripts. That is, a document describing rules by which
 script package should be packaged for Debian. As I managed to finally get it
 going again, I'm sending you the current version of the document (plus two
 scripts) to get your opinion about it (it was already semidiscussed on
 debian-policy). I'd do appreciate your opinion, as vim maintainer. Perhaps
 debian vim group can also help deploying this one into life?

 I see there are already some things remarks about policy in README.Debian of
 vim package. Perhaps we can polish whole thing up? :>

Best regards,

KT.
-- 
   __    __.---------------------------------------------------------------.__
  (oo)  |           Error finding COLDBEER.CAN   Sysop not loaded!            |
 / \/ \ |                                                                     |
 `V__V' `--.__penguin_#128720______________________________________________.--'

--ReaqsoxgOBHFXBhH
Content-Type: text/plain; charset=iso-8859-2
Content-Disposition: attachment; filename="vim-policy.txt"
Content-Transfer-Encoding: quoted-printable

$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 =A9 2003 Artur R. Czechowski, Jakub Turski

This manual is free software; you can redistribute it and/or modify it un=
der
the terms of the GNU General Public License as published by the Free Soft=
ware
Foundation; either version 2 of the License, or (at your option) any late=
r
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 vi=
mrc or
(better) compiling it in (if such solution is possible). New runtimepath =
should
look like this:

  runtimepath=3D~/.vim,/etc/vim,/usr/share/vim/vimfiles,/usr/share/vim/ad=
dons,/usr/share/vim/vim62,/usr/share/vim/vimfiles/after,~/.vim/after

This separation is proposed in order to get rid of versioning problem. Ri=
ght
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/add=
ons.
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 so=
urced
automatically. Therefore, administrators should think twice before instal=
ling
a script in this way.=20

If the particular user does not share this point of view, he has the opti=
on to
change this behaviour, by removing /usr/share/vim/addons from the runtime=
path.
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/ director=
y to
adequate files in /usr/share/vim/addons directory. This utility is availa=
ble
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 vers=
ion
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 scrip=
ts
with documentation should pre-depend on vim.



5. Naming.

All packages that contain vim scripts and adhere to this policy must be n=
amed
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/ dir=
ectory
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 t=
his
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 pa=
ckage
are NOT put into /usr/share/vim/addons/, and thus are NOT enabled by defa=
ult.
If user (or administrator) wants to enable one of the scripts from vim-sc=
ripts
package, he should copy it to specific directory (i.e. ~/.vim/).

If you are going to package a script with conformance to this policy, ple=
ase
check if it is included in vim-scripts package. If it is, please inform t=
he
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 separat=
e
packages are set of scripts (like latexSuite) or scripts that introduce s=
ome
sort of infrastructure (perl-support, with templates and dictionary file)=
 or
simply scripts that consist of more than one vim file.

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D

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>

--ReaqsoxgOBHFXBhH
Content-Type: text/plain; charset=iso-8859-2
Content-Disposition: attachment; filename=vim-install

#!/usr/bin/perl -w
# $Id: vim-install,v 1.2 2003/10/11 19:42:39 arturcz Exp $
# $Source: /var/lib/cvs/vsp/vim-install,v $

use File::Path;

my $db = "/var/lib/dpkg/info";
my $vim = "$ENV{HOME}/.vim";

sub install_script {
	# is there a parameter to take care of?
	if (!($_[0])) 
		{ die "Please specify the name of script to install.\n" };
	
	# is there ~/.vim?
	mkdir $vim;
	if ($! and ! -d $vim) 
		{ die "Something is wrong with your ~/.vim/ directory:\n$!\n" };
	
	# get the list of files and link them
	open(F,$db . "/vim-" . $_[0] . ".list") 
		or die "Script $_[0] has not been found.\nPerhaps it has not been installed site-wide from .deb package?\n";

	while (<F>) {
		chomp;
		if (m#^/usr/share/vim/addons/#) {
			($lf = $_)  =~ s#^/usr/share/vim/addons/##; $lf = "$vim/$lf";
			($ld = $lf) =~ s#/[^/]*?$##; 
			
			mkpath $ld;
			if ($! and ! -d $ld)
				{ die "Something is wrong with your $ld directory:\n$!\n" };
			
			symlink $_, $lf;
			if ($! and ! -l $lf)
				{ die "Something is wrong with your $lf symlink:\n$!\n" };

			if (readlink $lf ne $_)
				{ unlink $lf; symlink $_, $lf };

			print "$_ linked OK.\n";
		}
	}
	close(F);
	print "Script $_[0] has been installed.\n";
}

sub remove_script {
	# is there a parameter to take care of?
	if (!($_[0])) 
		{ die "Please specify the name of script to remove.\n" };
	
	# get the list of files and link them
	open(F,$db . "/vim-" . $_[0] . ".list") 
		or die "Script $_[0] has not been found.\nPerhaps it has not been installed site-wide from .deb package?\n";

	my $count=0;
	while (<F>) {
		chomp;
		if (m#^/usr/share/vim/addons/#) {
			($lf = $_)  =~ s#^/usr/share/vim/addons/##; $lf = "$vim/$lf";
			($ld = $lf) =~ s#/[^/]*?$##; 
			
			if (-l $lf)	{ 
				$!=0;
				unlink $lf;
				if ($!)	{ die "Something went wrong while removing $lf link:\n$!\n" };
				$count++;
				$dirs{$ld}++;
				print "$lf link removed OK.\n";
			}
			else {
				print "WARNING: $lf is NOT a symlink, please check it!\n";
			};
		}
	}
	close(F);
	if ($count) {
		print "Script $_[0] has been removed. $count links removed.\n";
		if (%dirs) { 
			print "Please check following dirs, they may have been emptied:\n", join "\n", sort(keys %dirs), "\n" };
	}
	else {
		print "Script $_[0] has NOT been removed.\nEither $_[0] wasn't installed in ~/.vim or you have messed something up...\n";
	};
}

for ($ARGV[0] || "help") {
        if (/^install$/)	{ install_script($ARGV[1]) }
        elsif (/^remove$/)	{ remove_script($ARGV[1])  }
        else				{ print 
"A script to manage ~/.vim -> /usr/share/vim/addons links.
usage: 
$0 command [options] where available commands are:
\tinstall foo\tcreates links from ~/.vim/ to /usr/share/vim/addons for script foo
\tremove foo\tremoves links from ~/.vim/ to /usr/share/vim/addons for script foo
\thelp\t\tget this help message
"; }
}


--ReaqsoxgOBHFXBhH
Content-Type: text/plain; charset=iso-8859-2
Content-Disposition: attachment; filename=helpztags

#!/usr/bin/perl
# helpztags generates tags for Vim helpfiles, for both .txt and .txt.gz files
# Author: Jakub Turski <yacoob@chruptak.plukwa.net>
#         Artur R. Czechowski <arturcz@hell.pl>
# $Id: helpztags,v 1.10 2003/10/11 20:17:44 arturcz Exp $
# $Source: /var/lib/cvs/vsp/helpztags,v $

# Please use following command for generate a manual file:
# pod2man -c "User Commands" -s 1 -q none -r "vim 6.2" -d "September 2003" helpztags helpztags.1

=head1 NAME

helpztags - generate the help tags file for directory

=head1 SYNOPSIS

helpztags F<DIRS>...

=head1 DESCRIPTION

F<helpztags> scans given directories for F<*.txt> and F<*.txt.gz> files.
Each file is scanned for tags used in F<vim> help files. For each directory
proper F<tags> file is generated.

There should be at least one directory given. In other case program exits
with error.

=head1 AUTHORS

Written by Jakub Turski and Artur R. Czechowski based on idea
contained in C<vim> sources for its C<:helptags command>.

=head1 REPORTING BUGS

Please use a Debian C<reportbug> command or procedure described at
C<http://bugs.debian.org/>. Corresponding package is vim.

=head1 SEE ALSO

Read C<:help helptags> in F<vim> for detailed information about helptags.

=cut

(undef,$rel)=split(/:/,'$Revision: 1.10 $');
$rel=~s/\$//g;
$date='$Date: 2003/10/11 20:17:44 $';
$header="helpztags v$rel";

use File::Glob ':globally';
use POSIX qw(getcwd);

print "$header\n";

($#ARGV==-1)&& die "Error: no directories given. Check manpage for details.\n";

$startdir=getcwd();

foreach $dir (@ARGV) {
  chdir $dir || die "Error: $dir: no such directory\n";
  print "Processing ".$dir."\n";
  open(TAGSFILE,">tags") || die "Error: Cannot open $dir/tags for writing.\n";
  foreach $file (<*.{gz,txt}>) {
    do { open(GZ, "zcat $file|") if ($file =~ /\.gz$/) } or open(GZ,$file);
    while (<GZ>) {
        # From vim61/src/ex_cmds.c, lines 5034-5036
        # 
        # Only accept a *tag* when it consists of valid
        # characters, there is no '-' before it and is followed
        # by a white character or end-of-line.
      while (/(?<!-)\*([^*\s]+?)\*\s+?/g) {
        $tags{$+}=$file;
      }
    }
    close(GZ);
  }
  map { print TAGSFILE "$_\t$tags{$_}\t/*"; s'\\'\\\\'g; s'/'\/'g; print TAGSFILE "$_*\n" } sort keys %tags;
  close TAGSFILE;
  chdir $startdir;
}

--ReaqsoxgOBHFXBhH--

--dDRMvlgZJXvWKvBx--