r863 - in /trunk/utils/addons: addons-proposal.txt registry-format.txt

Tue Jan 23 10:41:59 UTC 2007

Author: zack
Date: Tue Jan 23 11:41:58 2007
New Revision: 863

URL: http://svn.debian.org/wsvn/?sc=1&rev=863
Log:
revived the addons proposal (still to be revived the registry format)

Modified:
    trunk/utils/addons/addons-proposal.txt
    trunk/utils/addons/registry-format.txt

Modified: trunk/utils/addons/addons-proposal.txt
URL: http://svn.debian.org/wsvn/trunk/utils/addons/addons-proposal.txt?rev=863&op=diff
==============================================================================

--- trunk/utils/addons/addons-proposal.txt (original)
+++ trunk/utils/addons/addons-proposal.txt Tue Jan 23 11:41:58 2007
@@ -1,89 +1,94 @@
 
-handling of vim add-ons
-=======================
+Handling of Vim Addons
+======================
 
-vim add-ons
------------
+Vim "Addons"
+------------
 
-with "add-on" I refer to every additional (set of) feature that can be added to
-vim using its extension mechanisms (color schemes, syntaxes, indentation,
-plugin, ...)
+With "addon" we will refer to every additional (set of) feature that can be
+added to Vim using its extension mechanisms (color schemes, syntaxes,
+indentation, plugins, ftplugins, ...)
 
-current issues
+Present Issues
 --------------
 
-every vim add-on is currently installed in /usr/share/vim/addons/, directory
-which is in the runtimepath. As a consequence every installed add-on is always
+Every vim addon is currently installed in /usr/share/vim/addons/, directory
+which is in the runtimepath. As a consequence every installed addon is always
 enabled. The only way to choose which ones to load is to override the
 runtimepath so that /usr/share/vim/addons/ is not listed and manually load the
-desired one
+desired one.
 
-proposed solution
+The "vim-scripts" package is an exception to this rule installing everything
+under /usr/share/vim-scripts/ and requiring (as documented in the package's
+README.Debian) the sysadm (resp. local user) to symlink the desired addons to a
+system-wide directory (resp. ~/.vim). That is to say that none of the
+vim-scripts addons are enabled per default.
+
+Proposed Solution
 -----------------
 
-keep on installing add-ons under /usr/share/vim/addons/ (no changes are needed
-for all packages which ship add-ons), but remove this directory from the
+Keep on installing addons under /usr/share/vim/addons/ (no changes are needed
+for all packages which ship addons), but remove this directory from the
 runtimepath. Adds a directory /var/vim/addons/ to the runtimepath and implement
-a flexible symlink mechanism (a-la /etc/init.d/) to selectively enable add-ons.
+a flexible symlink mechanism (a-la /etc/init.d/) to selectively enable addons.
 
-implementation
+Implementation
 --------------
 
-1 registry, 1 tool.
+1 registry, 2 tools.
 
-The registry keep track of all installed vim add-ons, associating to each add-on
-name a list of files that should be in the runtimepath to enable the add-on.
-E.g., an entry in the registry can be:
+### The Addon Registry
 
-  Add-on: utl
-  Files: doc/utl_usr.txt, doc/utl_ref.txt, plugin/utl_rc.vim, plugin/utl.vim,
-   plugin/utl_scm.vim, plugin/utl_arr.vim, plugin/utl_uri.vim
+The registry keep track of all installed vim addons, associating to each addon
+name a list of files that should be in the runtimepath for the addon to be
+enabled. E.g., an entry in the registry can be (in YAML syntax):
 
-A single package can ship more than one add-on. Still, it is recommended that
-each package named vim-<name> installs a single add-on called <name> so that its
-easier for the user to know the canonical name of add-ons.
+  addon: utl
+  description: "Universal Text Linking: URL-based hyperlinking"
+  basedir: /usr/share/vim-scripts/
+  files:
+    - plugin/utl.vim
+    - doc/utl_ref.txt
+    - doc/utl_usr.txt
+    - plugin/utl_arr.vim
+    - plugin/utl_rc.vim
+    - plugin/utl_scm.vim
+    - plugin/utl_uri.vim
 
-The tool 'vim-addons' enables/disables plugins (in the same spirit as
-apache-modconf does for apache modules).
+A single package can ship more than one addon. Still, it is recommended that
+each package named vim-<name> installs a single addon called <name> so that its
+easier for the user to know the canonical name of addons. The "vim-scripts"
+package is an exception to this rule being conceived as a bundle of addons.
 
-When invoked as 'vim-addons update' (by sysadms), it reads as input
-/etc/vim/addons which lists names of enables add-ons, one per line. After
-invoking it, the symlinks under /var/vim/addons/ are all and only those
-corresponding to the addons listed /etc/vim/addons. This kind of invocation is
-idempotent.
+### Tool 1: update-vim-addons
 
-Other 'vim-addons' actions are meant to be used both by sysadms and users.
-Besides providing some query mechanisms (e.g. 'vim-addons list'), 'vim-addons'
-can be invoked to either "enable" or "enable" add-ons. When invoked by the
-sysadm to enable/disable add-ons it basically change /etc/vim/addons and re-run
-'update-vim-addons' (the actual implementation can be smarter than that and only
-change the needed symlinks). When invoked by the user it enables/disables
-add-ons acting on symlinks in the user directory ~/.vim/
+The tool "update-vim-addons" (to be used by sysadms) consumes as input the
+configuration file /etc/vim/addons which lists, one per line, the name of the
+addons which should be system-wide enabled. The invocation of
+"update-vim-addons" is idempotent.  Result of the invocation is the setting of
+all the needed symlinks pointing from /var/vim/addons/ to /usr/share/vim/addons/
+(or alternatively to the basedir specified in registry entries), and of course
+the removal of all the no longer needed symlinks.
 
-registry format
----------------
+Companion tools which automatically add/remove lines to /etc/vim/addons and then
+invoke update-vim-addons (a la apache-modconf) can be made available to be
+invoked by package postints.
 
-the registry can be as simple as a set of files installed under
-/usr/share/vim/registry/. We can think about providing a debhelper that looks
-for all files installed under /usr/share/vim/addons/ and create the
-corresponding registry entry installing it in the package or something similar.
+All packages shipping vim addons should have in their postinst scripts
+(conditional) invocations of the above companion tools so that, if the vim addon
+infrastructure is installed on the target machine, after the installation a
+given vim-addon is enabled per default. The invocation is conditional so that
+the installation of the addon infrastructure does not become a vim dependency
+(since vim itself ships some addons, e.g. matchit).
 
-miscellanea
------------
+### Tool 2: vim-addons
 
-* Automatic enabling of fresh installed add-on
-
-  It is a debian de-facto policy that installing a package just "makes it work".
-  To implement this, postinst scripts of vim addons should invoke 'vim-addons
-  enable <name>'
-
-* Disabling a system-wide enabled plugin
-
-  In order to support users willing to disable in their configuration add-ons
-  which are system-wide enabled an extra field could be added to the registry
-  listing a line that need to be added to ~/.vimrc to disable an add-on (e.g.
-  'let did_something = 1'). When invoked by users to disable a plugin such a
-  line will be added to some file automatically sourced by vim on startup.
+The tool "vim-addons" (to be used by users) can be used to enable/disable addons
+on a per user basis. It provides also inspecting facilities (e.g.: list the
+available addons or query their status for the current user). It additionally
+provides an override mechanism that let the user enable for her addons which are
+disabled system-wide and prevent the usage of addons which are enabled
+system-wide.
 
 --
-Thu, 11 May 2006 12:55:15 -0500 zack
+Tue, 23 Jan 2007 11:40:29 +0100 zack

Modified: trunk/utils/addons/registry-format.txt
URL: http://svn.debian.org/wsvn/trunk/utils/addons/registry-format.txt?rev=863&op=diff
==============================================================================
--- trunk/utils/addons/registry-format.txt (original)
+++ trunk/utils/addons/registry-format.txt Tue Jan 23 11:41:58 2007
@@ -1,3 +1,5 @@
+OUT OF DATE
+Tue, 23 Jan 2007 11:41:08 +0100 zack
 
 Format of Vim add-ons registry
 ==============================


