From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14894 invoked from network); 17 Jul 2003 16:47:33 -0000 Received: from sunsite.dk (130.225.247.90) by ns1.primenet.com.au with SMTP; 17 Jul 2003 16:47:33 -0000 Received: (qmail 5257 invoked by alias); 17 Jul 2003 16:47:28 -0000 Mailing-List: contact zsh-workers-help@sunsite.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 18866 Received: (qmail 5247 invoked from network); 17 Jul 2003 16:47:28 -0000 Received: from localhost (HELO sunsite.dk) (127.0.0.1) by localhost with SMTP; 17 Jul 2003 16:47:28 -0000 X-MessageWall-Score: 0 (sunsite.dk) Received: from [212.125.75.4] by sunsite.dk (MessageWall 1.0.8) with SMTP; 17 Jul 2003 16:47:28 -0000 X-VirusChecked: Checked X-Env-Sender: okiddle@yahoo.co.uk X-Msg-Ref: server-15.tower-1.messagelabs.com!1058460356!541693 X-StarScan-Version: 5.0.7; banners=.,-,- Received: (qmail 25840 invoked from network); 17 Jul 2003 16:45:57 -0000 Received: from iris.logica.co.uk (158.234.9.163) by server-15.tower-1.messagelabs.com with SMTP; 17 Jul 2003 16:45:56 -0000 Received: from gmcs3.local ([158.234.142.61]) by iris.logica.co.uk (8.12.3/8.12.3/Debian -4) with ESMTP id h6HGju7Y004589 for ; Thu, 17 Jul 2003 17:45:56 +0100 Received: from gmcs3.local (localhost [127.0.0.1]) by gmcs3.local (8.11.6/8.11.6/SuSE Linux 0.5) with ESMTP id h6HGlA513418 for ; Thu, 17 Jul 2003 18:47:10 +0200 X-VirusChecked: Checked From: Oliver Kiddle To: Zsh workers Subject: conventions for completion functions Date: Thu, 17 Jul 2003 18:47:10 +0200 Message-ID: <13416.1058460430@gmcs3.local> 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 ________________________________________________________________________