From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=DKIM_ADSP_CUSTOM_MED, FREEMAIL_FROM,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 27048 invoked from network); 7 Jul 2020 11:09:52 -0000 Received: from ns1.primenet.com.au (HELO primenet.com.au) (203.24.36.2) by inbox.vuxu.org with ESMTPUTF8; 7 Jul 2020 11:09:52 -0000 Received: (qmail 28067 invoked by alias); 7 Jul 2020 11:09:41 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: List-Unsubscribe: Sender: zsh-workers@zsh.org X-Seq: 46201 Received: (qmail 14830 invoked by uid 1010); 7 Jul 2020 11:09:41 -0000 X-Qmail-Scanner-Diagnostics: from park01.gkg.net by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.102.3/25863. spamassassin: 3.4.4. Clear:RC:0(205.235.26.22):SA:0(-2.3/5.0):. Processed in 1.232577 secs); 07 Jul 2020 11:09:41 -0000 X-Envelope-From: SRS0=DE6p=AS=yahoo.co.uk=okiddle@bounces.park01.gkg.net X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | Received-SPF: pass (ns1.primenet.com.au: SPF record at bounces.park01.gkg.net designates 205.235.26.22 as permitted sender) X-Virus-Scanned: by amavisd-new at gkg.net Authentication-Results: amavisd4.gkg.net (amavisd-new); dkim=pass (2048-bit key) header.d=yahoo.co.uk X-Greylist: domain auto-whitelisted by SQLgrey-1.8.0 X-YMail-OSG: CDkEC5gVM1kylTyJta.J_lhpqhCQFNslq_PtERX7.SAyQy8v_JLN3Fbp3H6R5Bc iQ8E9Nw9UAuzdrEBA9Jv6jj7Ca.50Zbz7EK0BhSA6WeFG5c7NtUs2z_ODe_xeCNOgk6AOaSecfLq 73TGvczhg_bUjswUdQH1xXlEWJNChfpXbrY3GbsRo8D3DeGNyXyaEre7xGzsjkc32D28CV_U7p.7 PE.D9MAKgRj5IK63MNKgnw3v.sV6pcuUDHntOfj76_9nKRKD87rQdjj66oQ4KBQ4bhSDCG8WAPpe u71y_2iVkr_H1rAPX4v6cPLTjX5_vAPKUFMetvRbh4VaWMP7lRITOgWcIXg43T9.6SbgRwmEmazj .ddR3MK.aijINuui4lV5Tq11_95QdG5m.pWqhCci42PBaMo9YzbzbdPs03oC6VAtNx_PSP4j7.3f SEM.8.MyTKWtEY7wr.D56vN9sYvqoqqhRg0.D4cV5K9ZTaQsNjBYypi69IkKqQua_7.4P4Mm5IkI bxF9akPS_T9oPtP0SjbcsWUWhfVIXv25ogf6UwRfz_tsE8ZIahGt6d_rLBv9.62j0Ixpk6DG9Iwj D1cs._xWhA81NUqm.62nfCrPJz3JoQ_MZ36JIiVwRWIfKkARkcMBeXa6afFcrVUY_4ux9MUnCmIh _S4RGIjxQ6viKACB9a3GzA7t9fPbk4WrZQVB9LIZQOXuSH2VnbDVf8o9ie17uIExuEl4Xjl_B0ZJ LShUrPdHDB_yvrbcK0UWVDoDIxWYQAByc1MMFktv21xymcCVuLEnVrlqFCnK1DghK9BfvFaXNKZU VtMYZf_SYQAt.WFRAFzlEI0P_ichjcQqBVTlzKUzD.xDX_hvpNKJaJGYwGpOtCp0Lr3V7hqg_IAU uqtSHpqwG40j5ymxyctGo5vZ5GmcxPuC8QQbL.IczTnIMnlJPJZE_zogW4QQP10BHhnXkGeBM7BV HAPhTFtyu.cCf8aHTonwesQ9kYKHcURAclrHSJvb62.aRSoLdRhEXX57Bi1VR2v1ZY33uUNWFDaI r62bchuu2nKQ9aM4LI3yZaa8kvcMRdMHlxt.5JVpe82kMNJaXmEHg.Kl_90Igy6A5bkt_OUu7Ov5 thB2bY5tyFdwfB0xS88QGDVuMvvsTYGjP4Shcvlfj4pMcdfTuLDnLlNafKTEQhPx1trnTPX0FIDF FMKXrh74FZDgeK32iuuAi5G5X2efmvI3s5aAfjRyQoti4ALXoo5AB9I0c9A0XhQ8M85s.nNX8qL6 hpM12QeB_L63cWHj.wKCMAGrjC2vCGvylmYorvilbq5zcLv8eTpcYphl4RW80e3h22wQlrC05Eok _xsX74qCtHpQMFiAzMXcTzIrZQLUtPOXyIHI7quh5OR_ci0Jbp.OzFyqdKmpA2R36c5Fm5W3IVkl 2ug-- To: zsh-workers@zsh.org In-reply-to: <8691-1594050559.938587@nS9U.7ujg.aulP> From: Oliver Kiddle References: <8691-1594050559.938587.ref@nS9U.7ujg.aulP> Subject: also document conventions in the style guide (was Re: PATCH: completion of X colours) MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-ID: <65536.1594120109.1@hydra> Date: Tue, 07 Jul 2020 13:08:49 +0200 Message-ID: <65542-1594120129.966175@zh4C.-tG4.q64T> X-Mailer: WebService/1.1.16197 hermes_yahoo Apache-HttpAsyncClient/4.1.4 (Java/11.0.7) 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,