r865 - /trunk/utils/addons/registry-format.txt

[zack at users.alioth.debian.org]

Author: zack
Date: Tue Jan 23 15:13:24 2007
New Revision: 865

URL: http://svn.debian.org/wsvn/?sc=1&rev=865
Log:
revived registry format description

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

Modified: trunk/utils/addons/registry-format.txt
URL: http://svn.debian.org/wsvn/trunk/utils/addons/registry-format.txt?rev=865&op=diff
==============================================================================
--- trunk/utils/addons/registry-format.txt (original)
+++ trunk/utils/addons/registry-format.txt Tue Jan 23 15:13:24 2007
@@ -1,30 +1,70 @@
-OUT OF DATE
-Tue, 23 Jan 2007 11:41:08 +0100 zack
 
-Format of Vim add-ons registry
-==============================
+Vim Addon Registry
+==================
 
-The registry is stored as a directory containing one file per add-on. Each file
-name corresponds to the add-on name.
+On-Disk Format
+--------------
 
-Each add-on is an RFC822 compliant file (the same format used by debian/control
-files) with the following fields (mandatory unless otherwise specified):
+The registry is stored on disk as a single directory directly (i.e. not in any
+sub-directory) containing a set of files in YAML [1] format. At the time of
+writing the directory containing the Vim addon registry is
+/usr/share/vim/registry/.
 
-- Add-On
-    name of the add-on, must be the same as the filename
-- Files
-    list of the files that should be present in one of the directories in the
-    vim runtimepath for the add-on to be enabled. Files are specified relative
-    to one of those dirs
-- Description
-    (optional, though highly recommended)
-    short, human understandable description of the add-on
-- Source
-    (optional, defaults to "/usr/share/vim/addons/")
-    where to find the files listed in the "Files" field. Used to provide add-on
-    descriptions of add-ons installed in non conventional ways (e.g. under
-    /usr/share/vim-scripts or provided by upstream e.g.
-    /usr/share/vim/vimcurrent/macros/)
+Each file is a multi-document YAML file (i.e. it can be composed by several
+different YAML documents separated by "---" lines). Each YAML document represent
+a registry entry, that is the information describing a single addon.
 
---
-Thu, 11 May 2006 12:55:24 -0500 zack
+Ideally, the registry directory contains one file per package shipping addons;
+with a filename obeying to the convention PACKAGE-NAME.yaml. Hence a single
+package can contribute to the registry with multiple entries described in a
+single YAML file.
+
+For example, the "vim-scripts" package should ship a single
+/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 (two
+space of indentation manually added to the present text file):
+
+  addon: alternate
+  description: "alternate pairing files (e.g. .c/.h) with short ex-commands"
+  basedir: /usr/share/vim-scripts/
+  files:
+    - plugin/a.vim
+    - doc/alternate.txt
+  ---
+  addon: whatdomain
+  description: "query the meaning of a Top Level Domain"
+  basedir: /usr/share/vim-scripts/
+  files:
+    - plugin/whatdomain.vim
+  ---
+
+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
+    field)
+
+  basedir:
+
+    directory where the files shipped by the addon (i.e. where the symlinks of
+    the user/sysadm should point to) reside on the filesystem (optional field,
+    default to: /usr/share/vim/addons)
+
+References
+----------
+
+[1] http://www.yaml.org/
+
+-- Tue, 23 Jan 2007 15:12:00 +0100 zack