Re: conventions for completion functions

[Oliver Kiddle <okiddle@xxxxxxxxxxx>]

Doug Kearns wrote:
> 
> It looks good to me, thanks.
> 
> You might like to add a note about supporting the latest stable versions
> of commands, as per your reply in 18353.

Okay, patch below adds that and a bit about tags being plural and
descriptions singular.

Index: Etc/completion-style-guide
===================================================================
RCS file: /cvsroot/zsh/zsh/Etc/completion-style-guide,v
retrieving revision 1.7
diff -u -r1.7 completion-style-guide
--- Etc/completion-style-guide	17 Jul 2003 17:30:55 -0000	1.7
+++ Etc/completion-style-guide	21 Jul 2003 11:54:04 -0000
@@ -17,7 +17,8 @@
   isn't room for it (see the next point) in which case put it on the
   next line un-indented.
 
-* Please try not to use lines longer than 79 characters.
+* Please try not to use lines longer than 79 characters. Don't worry
+  about breaking long `_arguments' or `_values' specs though.
 
 Descriptions:
 
@@ -49,6 +50,11 @@
 but use:
   '--timeout[specify connection timeout]:timeout (ms)'
   
+Group descriptions should be singular because only one thing is being
+completed even though many may be listed. This applies even where you
+complete a list of the things. Tags, functions for completing types of
+things (such as _files), and states should have plural names.
+
 In a function, allow any descriptions passed as an argument to override
 the default you define. For example:
   _wanted directories expl directory _files -/ "$@" -
@@ -64,6 +70,14 @@
 matches which are completely opposite in their meaning if it shortens
 the completion listing provided that the names of the matches makes it
 clear what their effect is.
+
+Command Versions:
+
+In most cases multiple versions (releases) of commands are not
+supported. The functions are merely updated to reflect the latest stable
+version. Exceptions to this can be made where are particular version
+continues to be commonly distributed. Where there is more than one variant
+of the same command however, the separate variants should be supported.
 
 Contexts, tags and all that
 ---------------------------

________________________________________________________________________
This email has been scanned for all viruses by the MessageLabs Email
Security System. For more information on a proactive email security
service working around the clock, around the globe, visit
http://www.messagelabs.com
________________________________________________________________________