zsh-workers
 help / color / mirror / code / Atom feed
From: Oliver Kiddle <okiddle@yahoo.co.uk>
To: zsh-workers@zsh.org
Subject: also document conventions in the style guide (was Re: PATCH: completion of X colours)
Date: Tue, 07 Jul 2020 13:08:49 +0200	[thread overview]
Message-ID: <65542-1594120129.966175@zh4C.-tG4.q64T> (raw)
In-Reply-To: <8691-1594050559.938587@nS9U.7ujg.aulP>

I wrote:
> I've also taken the opportunity to rename the cache variable. Using
> "cache" consistently as a prefix makes them easier to identify. And I
> think we try to declare them explicitly with typeset -g now.

Perhaps this should be documented as a convention. This adds a paragraph
to the style-guide. On checking over the style guide, I noticed some
minor errors and I think there is value in explicitly recommending the
use of imperative mood form for per-match descriptions. That is the
form used when telling someone to do something. So e.g. "skip matching
files". It's not uncommon that people write "skips matching files" which
is both longer and the lack of an explicit sentence subject is more
jarring.

Oliver

diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide
index 53d522764..cb5504370 100644
--- a/Etc/completion-style-guide
+++ b/Etc/completion-style-guide
@@ -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 both shorter and is 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,

      reply	other threads:[~2020-07-07 11:09 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <8691-1594050559.938587.ref@nS9U.7ujg.aulP>
2020-07-06 15:49 ` PATCH: completion of X colours Oliver Kiddle
2020-07-07 11:08   ` Oliver Kiddle [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=65542-1594120129.966175@zh4C.-tG4.q64T \
    --to=okiddle@yahoo.co.uk \
    --cc=zsh-workers@zsh.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).