[SCM] vim-addon-manager packaging branch, master, updated. v0.4.4-69-g5b98ccb

Mon Apr 9 00:23:15 UTC 2012

The following commit has been merged in the master branch:
commit ba5ed160ed83ce931ef761adc792fa6910b2b7c1
Author: Antonio Terceiro <terceiro at debian.org>
Date:   Sun Apr 8 21:09:53 2012 -0300

    Update documentation

diff --git a/TODO b/TODO
index 8eb8af1..a64ad83 100644
--- a/TODO
+++ b/TODO
@@ -11,8 +11,6 @@ Short term
 
 - update documentation:
 
-  + doc/addons-proposal.txt
-  + doc/registry-format.txt
   + vim-policy (debian/policy/ on vim source package)
 
   Note the fact that new-style addons must provide pre-built tag files
@@ -51,4 +49,4 @@ Middle/Long term
 
 - look closer at http://www.vim.org/scripts/script.php?script_id=2905
 
-  vim-addon-manager should not be "Debian specific"
+  we must fix the view that vim-addon-manager is "Debian specific"
diff --git a/doc/addon-directory.markdown b/doc/addon-directory.markdown
new file mode 100644
index 0000000..44116ed
--- /dev/null
+++ b/doc/addon-directory.markdown
@@ -0,0 +1,72 @@
+# vim-addon-manager: one addon per directory
+
+The original addon format used by vim-addon-manager has a serious problem. When
+you have the addon installed (say, into your ~/.vim), then you have one symlink
+for each file contained by the addon. When that addon is upgraded system-wide
+and new files are added, or existing files are removed, then it effectively
+becomes broken, because you will either have missing symlinks or broken ones.
+
+Another problem with the current addon system is that you cannot easily install
+new addons that are not packaged.
+
+This new addon type tries to solve both issues.
+
+## Registry entry
+
+The registry file for directory addons must be like this:
+
+    addon: my-addon
+    description: "new style addon with a directory instead of files"
+    type: directory
+    directory: /path/to/my/addon
+
+The "type" field must contain the value "directory".
+
+The "directory" field must contain the path were the addon is installed. If
+this field is omitted, vim-addon-manager will assume that the addon was
+installed to /usr/share/vim/addons/vam/$(addon), where $(addon) is the addon
+name from the "addon" field.
+
+## Addon contents
+
+Each addon must reproduce the contents of a vim runtimepath directory, i.e. it
+can contain subdirectories doc/, plugin/, autoload/, syntax/, etc. For example, the migrated vim-rails package installs the following files.
+
+/usr/share/vim/addons/vam/rails/doc/tags
+/usr/share/vim/addons/vam/rails/doc/rails.txt
+/usr/share/vim/addons/vam/rails/plugin/rails.vim
+/usr/share/vim/addons/vam/rails/autoload/rails.vim
+
+These files were previously installed directly into /usr/share/vim/addons, and
+they are now being installed to /usr/share/vim/addons/vam/rails.
+
+When such an addon is installed vim `vim-addon-manager install rails`, you will
+end up with a symlink at ~/.vim/vam/rails pointing at
+/usr/share/vim/addons/vam/rails. That symlink will be added to the vim
+runtimepath during startup.
+
+## Tags files
+
+Since the installation involves a single symlink to a directory writable only
+by root, new style addons must include pre-buit tags files. Note the listing of
+the vim-rails package above: it already includes a tags file under `doc/tags`.
+
+## Migrating from the old-style addon format
+
+If you maintain an existing addon and want to migrate it to the new addon
+format, follow these steps:
+
+* add a "type" field to the registry file, with "directory" as value
+* rename the "files" field to "legacy\_files". This will help vim-addon-manager
+  with upgrading the addon.
+* change the package to install to /usr/share/vim/addons/vam/$(addon) instead
+  of scatering its files into /usr/share/vim/addons.
+
+During package upgrades, a dpkg trigger vim vim-addon-manager will remove the
+existing multiple symlinks from the target directory and install the new
+symlink into $(target\_dir)/vam.
+
+## See also
+
+See the dh-vim-addon package, which automates most of the work needed to
+package vim addons in this new format supported by vim-addon-manager.
diff --git a/doc/registry-format.txt b/doc/registry-format.txt
index 511eb9e..6c07bf7 100644
--- a/doc/registry-format.txt
+++ b/doc/registry-format.txt
@@ -49,12 +49,41 @@ the YAML specification:
 
     human understandable textual description of the addon (required field)
 
+  type:
+
+    The type of the addon. Currently there are two types of addons.
+
+    Addons with type "legacy" (the default) are old-style addons: each of its
+    files (listed in the "files" field) will be symlinked into the target
+    installation directory.
+
+    Addons with type "directory" must install to a single directory, and their
+    installation will result in a single symlink under $target_dir/vam, which
+    will be added to vim's runtimepath. This is the recommended addon type; see
+    addon-directory.markdown for details.
+
+    If the "type" field is ommitted, it is assumed "legacy". This is to keep
+    backwards compatibility with previous addons.
+
   files:
 
     list of the files which compose the addon and are required to be present in
     a component of the Vim runtime path for the addon to be enabled.  Each file
     is specified relative to a component of the Vim runtime path (required
-    field)
+    field for addons of type "legacy".)
+
+  directory:
+
+    for addons of type "directory", this field should indicate the directory in
+    which the addon is installed. If ommitted, it is assumed the addon is
+    installed to a subdirectory of /usr/share/vim/addons/vam.
+
+  legacy_files:
+
+    for addons that were of type "legacy" and migrated to the type "directory",
+    this field must list the files that the addon used to contain. This
+    information is used when trying to automatically upgrade the addons
+    installed by users from the old format to the new format.
 
   basedir:
 
diff --git a/lib/vim/addon_manager/addon.rb b/lib/vim/addon_manager/addon.rb
index 9ce887d..9159c33 100644
--- a/lib/vim/addon_manager/addon.rb
+++ b/lib/vim/addon_manager/addon.rb
@@ -104,10 +104,11 @@ module Vim
       alias_method :addon, :name
 
       def self.build(yaml, basedir)
-        if yaml['files']
-          Vim::AddonManager::Addon::Legacy.new(yaml, basedir)
-        else
+        case yaml['type']
+        when 'directory'
           Vim::AddonManager::Addon::Directory.new(yaml, basedir)
+        else
+          Vim::AddonManager::Addon::Legacy.new(yaml, basedir)
         end
       end
 
diff --git a/spec/data/registry/newstyle.yaml b/spec/data/registry/newstyle.yaml
index 64a82b7..b2147e1 100644
--- a/spec/data/registry/newstyle.yaml
+++ b/spec/data/registry/newstyle.yaml
@@ -1,2 +1,3 @@
 addon: newstyle
 description: "new style addon with a directory instead of files"
+type: directory
diff --git a/spec/data/registry/newstylemigrated.yaml b/spec/data/registry/newstylemigrated.yaml
index f07069f..9f88667 100644
--- a/spec/data/registry/newstylemigrated.yaml
+++ b/spec/data/registry/newstylemigrated.yaml
@@ -1,5 +1,6 @@
 addon: newstylemigrated
 description: "new style addon that had a previous old-style version"
+type: directory
 legacy_files:
   - syntax/newstylemigrated.vim
   - ftplugin/newstylemigrated.vim
diff --git a/spec/data/registry/newstylewithdir.yaml b/spec/data/registry/newstylewithdir.yaml
index 99a3fc7..e1f155b 100644
--- a/spec/data/registry/newstylewithdir.yaml
+++ b/spec/data/registry/newstylewithdir.yaml
@@ -1,4 +1,5 @@
 addon: newstylewithdir
 description: "new style addon with a directory instead of files"
+type: directory
 directory: /path/to/newstylewithdir
 

-- 
vim-addon-manager packaging

