r865 - /trunk/utils/addons/registry-format.txt
zack at users.alioth.debian.org
zack at users.alioth.debian.org
Tue Jan 23 14:13:25 UTC 2007
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
More information about the pkg-vim-maintainers
mailing list