* conventions for completion functions
@ 2003-07-17 16:47 Oliver Kiddle
2003-07-19 6:24 ` Doug Kearns
0 siblings, 1 reply; 3+ messages in thread
From: Oliver Kiddle @ 2003-07-17 16:47 UTC (permalink / raw)
To: Zsh workers
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
________________________________________________________________________
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: conventions for completion functions
2003-07-17 16:47 conventions for completion functions Oliver Kiddle
@ 2003-07-19 6:24 ` Doug Kearns
2003-07-21 11:59 ` Oliver Kiddle
0 siblings, 1 reply; 3+ messages in thread
From: Doug Kearns @ 2003-07-19 6:24 UTC (permalink / raw)
To: zsh-workers
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: conventions for completion functions
2003-07-19 6:24 ` Doug Kearns
@ 2003-07-21 11:59 ` Oliver Kiddle
0 siblings, 0 replies; 3+ messages in thread
From: Oliver Kiddle @ 2003-07-21 11:59 UTC (permalink / raw)
To: zsh-workers
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
________________________________________________________________________
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2003-07-21 11:58 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2003-07-17 16:47 conventions for completion functions Oliver Kiddle
2003-07-19 6:24 ` Doug Kearns
2003-07-21 11:59 ` Oliver Kiddle
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).