mirrors/zsh
1
0
Fork 0
mirror of git://git.code.sf.net/p/zsh/code synced 2026-01-07 22:11:15 +01:00
Code Releases Activity

46201: add guidelines for caching and use of imperative mood in descriptions

Browse source
This commit is contained in:
Oliver Kiddle 2020-07-08 17:47:46 +02:00
parent 389c853b4a
commit 57a735f6b9
2 changed files with 24 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

3
ChangeLog
View file

@ -1,5 +1,8 @@
2020-07-08 Oliver Kiddle <okiddle@yahoo.co.uk>
* 46201 (tweaked per Daniel): Etc/completion-style-guide: add
guidelines for caching and use of imperative mood in descriptions
* 46195: Completion/X/Type/_x_color: use showrgb command to get
colours if it is available

25
Etc/completion-style-guide
View file

@ -44,7 +44,10 @@ 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.
generally appears in uppercase. Prefer the use of the imperative
mood as it is shorter and more natural in the absence of an explicit
subject for a sentence, e.g. "recurse subdirectories" instead of
"recurses subdirectories", as if orders are being given.
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
@ -121,7 +124,7 @@ 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 (e.g., the command takes different options
different platforms), the separate variants should be supported.
on different platforms), the separate variants should be supported.
Contexts, tags and all that
---------------------------
@ -433,7 +436,7 @@ keep things consistent).
Descriptions
------------
Always use description. This is important. Really. *Always* use
Always use descriptions. This is important. Really. *Always* use
descriptions. If you have just written down a `compadd' without a
"$expl[@]" (or equivalent), you have just made an error. Even in
helper functions where you use a "$@": if you can't be sure that there
@ -486,6 +489,20 @@ is all you need to make your function work correctly with both tags
and description at the same time.
Caching
-------
Where generating matches takes a long time it can be useful to save
the list for reuse in subsequent completion attempts. If you use
a global variable, prefix the name of it with `_cache_' and explicitly
declare it with `typeset -g'. In many cases this is sufficient but
where generating matches takes especially long or the list is
especially large, use the `_store_cache` mechanism to allow for a
persistent cache. When caching matches, also consider whether
generated matches might be affected by style settings for limited
contexts and adapt to allow such configuration to work.
Misc. remarks
-------------
@ -513,7 +530,7 @@ Misc. remarks
6) When matches with a common prefix such as option names are generated,
add them *with* the prefix (like `-', `+', or `--' for options).
Then check the `prefix-needed' style to see if the matches are to be
added when the prefix is on the line and use the `prefix-hidden'
added when the prefix is not on the line and use the `prefix-hidden'
style to see if the prefix should be listed or not.
7) If at all possible, completion code for a command or a suite of
commands should go into only one file. If a command has sub-commands,