conventions for completion functions

conventions for completion functions

[Oliver Kiddle]

The various conventions related to completion functions aren't documented
anywhere. This has come up a few times in off-list discussions - recently
with Doug and I think with Felix (relating to the output of his XML stuff)
in the past.

The following patch adds a section to the completion-style-guide file
to document them. Let me know if you think of any other points I should
make or if you disagree with any of the points.

Oliver

Index: Etc/completion-style-guide
===================================================================
RCS file: /cvsroot/zsh/zsh/Etc/completion-style-guide,v
retrieving revision 1.6
diff -u -r1.6 completion-style-guide
--- Etc/completion-style-guide	2 Apr 2001 13:04:05 -0000	1.6
+++ Etc/completion-style-guide	17 Jul 2003 16:34:13 -0000
@@ -1,3 +1,70 @@
+Conventions
+-----------
+
+There are a number of conventions related to writing completion
+functions and it is useful if they are followed for functions which are
+to be distributed as part of zsh to maintain a level of consistency.
+
+Coding style:
+
+* Use two spaces for indentation and four for continuation lines except
+  where there are many continutation lines such as `_arguments' or
+  `_values' specs. Lines tend to be longer than in C code so less
+  indentation makes sense.
+
+* For constructs such as `if' and `while', the `then' or `do' should be
+  on the end of the line after a semi-colon and space unless there
+  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.
+
+Descriptions:
+
+Descriptions should not have a trailing full stop and initial capital
+letter. Though capitals are fine where you have an acronym which
+generally appears in uppercase. 
+
+It is a good idea to copy descriptions from the command's man page or
+--help output. If you do this, be careful that the description still
+makes sense. Some commands have a description like `print help message
+(this one) and exit' for --help but the `(this one)' part no longer
+makes sense. A less obvious example is where the help output looks like:
+  -X, --encoding=NAME        use input encoding NAME
+copying this description exactly would result in completion output that
+looks like this:
+  --encoding   -X    -- use input encoding NAME
+In the help output, it is much clearer what is meant by `NAME' because
+it appears after `--encoding=' but it doesn't in the completion
+listing. So it is better to use a description of this form:
+  --encoding   -X    -- use specified input encoding
+The word specify is commonly used with options that take arguments.
+
+Another example of where --help output may not be suitable unedited is
+where default values or units are indicated. Do not put them in
+per-match descriptions; they are better placed in the group
+descriptions. Put the units in parentheses after the description. So
+for example, do not use:
+  '--timeout[specifiy connection timeout in milliseconds]:timeout'
+but use:
+  '--timeout[specify connection timeout]:timeout (ms)'
+  
+In a function, allow any descriptions passed as an argument to override
+the default you define. For example:
+  _wanted directories expl directory _files -/ "$@" -
+The "$@" adds descriptions passed as parameters and the trailing `-'
+tells _wanted where to put options specifying the `directory' description.
+
+Where two matches have identical meaning, give them the same
+description so that the completion system can group them together.
+Conventionally a brace exapansion of this form is used:
+  '(--context,-C)'{--context=,-C-}'[specify lines of context]:lines'
+You won't need the exclusion list if the option can be specified
+multiple times. It can also be useful to use the same description for
+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.
+
 Contexts, tags and all that
 ---------------------------
 
@@ -410,4 +477,4 @@
     with its exit status. After this call to `call_function' the
     completion function would contain the code for the default way to
     generate the matches.
-    See the `_rpm' and `_nslookup' files for examples.
+    See the `_email_addresses', `_rpm' and `_nslookup' files for examples.

________________________________________________________________________
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
________________________________________________________________________

Re: conventions for completion functions

[Doug Kearns]

On Thu, Jul 17, 2003 at 06:47:10PM +0200, Oliver Kiddle wrote:

<snip>
 
> The following patch adds a section to the completion-style-guide file
> to document them. Let me know if you think of any other points I should
> make or if you disagree with any of the points.

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.

Regards,
Doug

Re: conventions for completion functions

[Oliver Kiddle]

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
________________________________________________________________________