[SCM] vim-addon-manager packaging branch, master, updated. e674a4b7fb3a73b1e95f07db028e559f2d1bb0da

[James Vega]

The following commit has been merged in the master branch:
commit e674a4b7fb3a73b1e95f07db028e559f2d1bb0da
Author: James Vega <jamessan at debian.org>
Date:   Wed Jan 20 19:21:21 2010 -0500

    Add a man page describing the registry file format.
    
    Closes: #457040
    
    Signed-off-by: James Vega <jamessan at debian.org>

diff --git a/debian/changelog b/debian/changelog
index e88ea54..c9a91b5 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -12,6 +12,7 @@ vim-addon-manager (0.4.2) UNRELEASED; urgency=low
   * Include the target directory in the install/remove informational messages.
     (Closes: #499563)
   * Fix a spelling error in vim-addons(1).
+  * Add a man page describing the registry file format.  (Closes: #457040)
 
  -- James Vega <jamessan at debian.org>  Fri, 24 Jul 2009 19:56:48 +0200
 
diff --git a/debian/vim-addon-manager.manpages b/debian/vim-addon-manager.manpages
index 0345e4e..111103f 100644
--- a/debian/vim-addon-manager.manpages
+++ b/debian/vim-addon-manager.manpages
@@ -1 +1,2 @@
 src/vim-addons.1
+doc/vim-registry.5
diff --git a/doc/registry-format.txt b/doc/registry-format.txt
index 29cc4e2..511eb9e 100644
--- a/doc/registry-format.txt
+++ b/doc/registry-format.txt
@@ -42,15 +42,15 @@ Each registry entry may contain the following fields, to be typeset according to
 the YAML specification:
 
   addon:
-  
+
     name of the addon (required field)
 
   description:
-  
+
     human understandable textual description of the addon (required field)
 
   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
@@ -62,6 +62,14 @@ the YAML specification:
     the user/sysadm should point to) reside on the filesystem (optional field,
     default to: /usr/share/vim/addons)
 
+  disabledby:
+
+    vim script command that can be used (usually by adding it to ~/.vimrc) to
+    prevent the addon from being used even when it is installed.  The intended
+    usage of this field is to "blacklist" an undesired addon whose files are
+    available, and hence automatically loaded by Vim, in a component of the
+    Vim runtime path.  (optional field)
+
 References
 ----------
 
diff --git a/doc/vim-registry.5 b/doc/vim-registry.5
new file mode 100644
index 0000000..a0f76be
--- /dev/null
+++ b/doc/vim-registry.5
@@ -0,0 +1,81 @@
+.TH vim-registry 5 "January 2010" "Debian Project" "vim addons"
+.SH NAME
+vim\-registry \- syntax for vim\-addons registry files
+.SH SYNOPSIS
+.I PACKAGE\-NAME.yaml
+.SH DESCRIPTION
+A registry file is a multi-document YAML file (i.e. it can be composed by
+several different YAML documents separated by \*(lq\-\-\-\*(rq lines). Each YAML
+document represents a registry entry, that is the information describing a
+single addon.
+
+Ideally, the registry directory contains one file per package shipping addons;
+with a filename obeying to the convention
+.IR PACKAGE\-NAME.yaml .
+Hence a single package can contribute to the registry with multiple
+entries described in a single YAML file.
+
+For example, the \*(lqvim-scripts\*(rq package should ship a single
+.I /usr/share/vim/registry/vim-scripts.yaml
+file, containing one YAML document per shipped addon. The first lines of such
+file can look like the following:
+.PP
+.RS 4
+.EX
+addon: alternate
+description: "alternate pairing files (e.g. .c/.h) with short ex\-commands"
+basedir: \fI/usr/share/vim\-scripts/\fR
+disabledby: "let loaded_alternateFile = 1"
+files:
+  \- \fIplugin/a.vim\fR
+  \- \fIdoc/alternate.txt\fR
+\-\-\-
+addon: whatdomain
+description: "query the meaning of a Top Level Domain"
+basedir: \fI/usr/share/vim-scripts/\fR
+disabledby: "let loaded_whatdomain = 1"
+files:
+  \- \fIplugin/whatdomain.vim\fR
+\-\-\-
+.EE
+.RE
+.PP
+Each registry entry may contain the following fields, to be typeset according to
+the YAML specification:
+.TP
+addon (Required)
+Name of the addon.
+.TP
+description (Required)
+Human understandable textual description of the addon.
+.TP
+files (Required)
+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.
+.TP
+basedir (Optional)
+Directory where the files shipped by the addon (i.e., where the symlinks of
+the user/sysadm should point to) reside on the filesystem.  Default is
+.IR /usr/share/vim/addons .
+.TP
+disabledby (Optional)
+Vim script command that can be used (usually by adding it to \fI~/.vimrc\fR)
+to prevent the addon from being used even when it is installed.  The intended
+usage of this field is to \*(lqblacklist\*(rq an undesired addon whose files
+are available, and hence automatically loaded by Vim, in a component of the
+Vim runtime path.
+.SH AUTHOR
+James Vega <jamessan at debian.org>
+.SH SEE ALSO
+.BR vim\-addons (1),
+.UR http://www.yaml.org/
+YAML specification
+.UE
+.SH COPYRIGHT
+Copyright (C) 2010 James Vega
+.PP
+This program is free software, you can redistribute it and/or modify it under
+the terms of the GNU General Public License version 3 as published by the
+Free Software Foundation; either version 3 of the License, or (at your
+option) any later version.

-- 
vim-addon-manager packaging