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=-3.3 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 11669 invoked from network); 21 Dec 2022 02:01:14 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 21 Dec 2022 02:01:14 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20210803; t=1671588074; b=O0El8UISAoispTw8Ig1abizt0Rt78bNZmUwDlOHtmKYKScUhklNzgKx40f59q8Mt8BRqXMiUvc Nw3Fpy0b0kr1Lxb/IH2Iv0f73x6VIpAcTvTlPqRa9dVeVjdPORqh9RtpxaaiPwx5AmArAUlDcM whpAIyJcI/yz/joNZI1LUHK1bygbulwzA+1u/wbkVYMTD+SFkmDBIs7LfsyCBlj5fa1c4Pbs6q /TLGyYGpzR0khztMXjIYwyrd8TTjiCrNJNdo7ZQkI0NdtoteQISbt/wKcjfpOvJYjF8+d9jCRg ewFcMjzYtPw0QZaVrJHbJVRGJxKQ7oNtDMEw5bOJWRI5iQ==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (out3-smtp.messagingengine.com) smtp.remote-ip=66.111.4.27; dkim=pass header.d=daniel.shahaf.name header.s=fm1 header.a=rsa-sha256; dkim=pass header.d=messagingengine.com header.s=fm2 header.a=rsa-sha256; dmarc=none header.from=daniel.shahaf.name; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20210803; t=1671588074; bh=C67eWRqs1tv/MP8Okipyi/oa7dFjKLf4/VsBaRiqR0c=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:In-Reply-To:Content-Transfer-Encoding:Content-Type: MIME-Version:References:Message-ID:Subject:Cc:To:From:Date:DKIM-Signature: DKIM-Signature:DKIM-Signature; b=UWl5h7zMORjNdUgYdinHj2M7bp3Ta5K3eGn72DiTg9mHbZw/1dDECfsVDbsWKg5x9xav1yYICh mnwStebtfx0ivD9QuOBNQvEjPEUstV1LVWD/hl6j90RsKOJDgD1jAzjnpYqrdy2n7SOFVlWC9R UWlMVffdobo2DYghQFLUE+x4jAlDJ+iUaUasWVZHZGPHNak8Vd9OZphh/i+nF9o/x3DKIZ9i0T 8fqRbKHMZS7IESjwg70yKRWjbMi3Y2tv5uDXzmYrC39CoWao6pXhzjETIKbePvvYDdPSA2FHPS 9warpdJkXpMZehIQQ8XPSwp5sCvUJG+fqXziEMUz0r8luA==; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=zsh.org; s=rsa-20210803; h=List-Archive:List-Owner:List-Post:List-Unsubscribe: List-Subscribe:List-Help:List-Id:Sender:In-Reply-To:Content-Transfer-Encoding :Content-Type:MIME-Version:References:Message-ID:Subject:Cc:To:From:Date: Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender :Resent-To:Resent-Cc:Resent-Message-ID; bh=KvsApJcxv1J7F1AIrwaGcVA/0NLFGft+PKEC39p4RhA=; b=jObQXKzA+h85mmkUR+XBLf82+b 4SCerfLMXSCt/ua0sxDEqfDyCV62pgxyrPNvYRo30BxzzO+FF2NV8W1JJROr7E0k51UsJGutILrCS HmfMpwzzV5XbaNMW+esu/SwReY2CX4pjd43piRwHZ9fXK+TsQkIiQfjZ7MbKK+hqQ9nIYXwVRbiKM aiocefm+UOV7TFngisKH0SkpZUjcU1Qg40FqQ6g5CjPZPhcHKtKUEX5ms4Ck7qNqVvg+w3Hj/bdUT HYO1f7Y2kPpUEN6B/mzVfajqYoo1H+zxfaHmPjDOpjsceOknFXsCg2GVjEGzXh8rpiubFRj+Bejlf NYLNMi3A==; Received: by zero.zsh.org with local id 1p7oPy-000Dds-1k; Wed, 21 Dec 2022 02:01:14 +0000 Authentication-Results: zsh.org; iprev=pass (out3-smtp.messagingengine.com) smtp.remote-ip=66.111.4.27; dkim=pass header.d=daniel.shahaf.name header.s=fm1 header.a=rsa-sha256; dkim=pass header.d=messagingengine.com header.s=fm2 header.a=rsa-sha256; dmarc=none header.from=daniel.shahaf.name; arc=none Received: from out3-smtp.messagingengine.com ([66.111.4.27]:45241) by zero.zsh.org with esmtps (TLS1.3:TLS_AES_256_GCM_SHA384:256) id 1p7oPH-000Czd-AJ; Wed, 21 Dec 2022 02:00:33 +0000 Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailout.nyi.internal (Postfix) with ESMTP id 2D0B45C0165; Tue, 20 Dec 2022 21:00:29 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute1.internal (MEProxy); Tue, 20 Dec 2022 21:00:29 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= daniel.shahaf.name; h=cc:cc:content-transfer-encoding :content-type:date:date:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:sender:subject :subject:to:to; s=fm1; t=1671588029; x=1671674429; bh=KvsApJcxv1 J7F1AIrwaGcVA/0NLFGft+PKEC39p4RhA=; b=OAeU6L5T2XkaHIRAt2JgGAccTx C33ffkQWlxB1w24KUxkD7WhKzKbagtQ3taf7tEOenbFUN1gEVT+o8TF9ViUKif7P FJmJO9HWl7LfSLEZ183qKb7KoY3GYXCnHYc54ruIFmGoSynm882g7fUJYumWPnfR h4r6y+rnUoAsPLB55QeBEleaHNrA62mvqyAtIwNqpta77zXPm9WP5gl915H0FNFG cP14+mCX5Ec6Gm2zFTE4TOslaaQ0y5etJJyM2HsSeYJwOqM3RTjcxGypoxIjeVnv +euxXKzGi1n/ghNB5CEy0jdHi3hCax3QyouV1zQmCH3dgJ5LTYmGJXsHb5iQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-transfer-encoding :content-type:date:date:feedback-id:feedback-id:from:from :in-reply-to:in-reply-to:message-id:mime-version:references :reply-to:sender:subject:subject:to:to:x-me-proxy:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm2; t=1671588029; x= 1671674429; bh=KvsApJcxv1J7F1AIrwaGcVA/0NLFGft+PKEC39p4RhA=; b=k MB6VmJZKhtAGzvVkxrePiNlBijEZVrL4jcEtkBDqfcJswJwZ22OhNjCPC5Y6iqov dfGr7kd0IbWhSq57bmvUojETG1V7kg+9Z9KS/FqTHeUQPWzXdDMrOPNKSNNLGQaI JZWlo8QjGcUQocy85AzUEyic9mwjA63wrDvW3gX4POI9TiYZiE2Z9xkhW7Dr609l UR0JRRR6UR6xhmC5omyKzDetUOecUtgy/CSNaz5g+Zq6iwk794VfGKZB3QOYzx+E 6y+nNFRNzxrO6rQbKtjtx3UVsu3OgUXpOaySUBNe0VMSM35sXIGlv0wAd+qkeR1d TyaCvtH9wWWIrJyzkNr/Q== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedrgeejgdegudcutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpeffhffvvefukfhfgggtugfgjggfsehtkedttddtreejnecuhfhrohhmpeffrghn ihgvlhcuufhhrghhrghfuceougdrshesuggrnhhivghlrdhshhgrhhgrfhdrnhgrmhgvqe enucggtffrrghtthgvrhhnpeeuheelvdfggeeukeffteduveeluefgleegtdfggefgjeej vdefveffteffjeeiffenucffohhmrghinhepfhhrvggvsghsugdrohhrghenucevlhhush htvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpegurdhssegurghnihgv lhdrshhhrghhrghfrdhnrghmvg X-ME-Proxy: Feedback-ID: i425e4195:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 20 Dec 2022 21:00:28 -0500 (EST) Received: by tarpaulin.shahaf.local2 (Postfix, from userid 1000) id 4NcGqZ5TVtz2wN; Wed, 21 Dec 2022 02:00:26 +0000 (UTC) Date: Wed, 21 Dec 2022 02:00:26 +0000 From: Daniel Shahaf To: Ray Andrews Cc: Zsh Users Subject: Re: manual Message-ID: <20221221020026.GH8411@tarpaulin.shahaf.local2> References: <71c9c7e9-3f95-143d-fbd6-6575d7f4c446@eastlink.ca> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <71c9c7e9-3f95-143d-fbd6-6575d7f4c446@eastlink.ca> User-Agent: Mutt/1.10.1 (2018-07-13) X-Seq: 28600 Archived-At: X-Loop: zsh-users@zsh.org Errors-To: zsh-users-owner@zsh.org Precedence: list Precedence: bulk Sender: zsh-users-request@zsh.org X-no-archive: yes List-Id: List-Help: , List-Subscribe: , List-Unsubscribe: , List-Post: List-Owner: List-Archive: Ray Andrews wrote on Tue, Dec 20, 2022 at 14:41:44 -0800: > Daniel was interested in what I'd do with the 'set' man page.  It has a > completely different flavor but: > Thanks. I was hoping you'd send new text just for that one three-line paragraph, actually. Glad to see more, but I don't have time to review more, unfortunately, so I'll reply just to parts: > 3): set {+|-}s -A [ARRAY_NAME] [VALUE] > 4): set        +A [ARRAY_NAME] [VALUE]         # sorting not available with ⋮ > 3,4) An array will be set.  Notice there is no equal sign and the array > members are NOT to be enclosed in parentheses. The last sentence goes without saying, for several reasons: - As a rule, the manual isn't in the business of describing what the syntax is not; the manual should describe what the syntax /is/. Putting =(…) there isn't nearly common enough an error to make an exception to the rule for. - The synopsis doesn't show any equals signs or parentheses. - «set» is a builtin. The basic syntax of calling builtins, functions, and external commands is documented elsewhere in the manual, and in the context of this section is assumed knowledge. The assumed knowledge includes the fact that calling any builtin, function, or external command with anything enclosed in parentheses would be a syntax error. To see this: . f() { } for i in "autoload" "f" "/usr/bin/env" "[["; do "$i" done The fourth one fails, because «[[» is a keyword, and results of expansion are not considered as keywords. All of the first three work, because they all follow exactly the same "list of shell words" syntax; the only difference between them is what relative order they are considered (looked up) in. (Functions are looked up first, which is why a function named "autoload" or "env" would shadow the builtin or the external command respectively.) > 3): set {+|-}s -A [ARRAY_NAME] [VALUE]: > ARRAY_NAME is set to VALUE, completely erasing any former contents: > Normally the manual would end such a sentence at the comma. Rule against surplusage, I guess ☺ > 4): set +A [ARRAY_NAME] [VALUE]: > ARRAY_NAME is overwritten by the new VALUE but not truncated if the new > VALUE is shorter than the old. > Unfortunately, as written this assumes the reader takes "overwriting" to be an operation that involves "truncation" at some point, and we can't assume the reader's mental model of overwriting is that. > Note that 'typeset -A' is quite different from 'set -A'!  If you are copying > an > associative array to another array you must do this: > > $ typeset -A NEW_ARRAY > $ set -A NEW_ARRAY OLD_ARRAY > > ... otherwise NEW_ARRAY will not be associative.  Be warned. Good point. Right now the docs of -A just say the parameter "is set to an array", which could be taken to mean it's forced to be a numerically-indexed array. So, that's a second issue in this section we should fix. > COMMENTS ON MAN PAGE: > > >               argFor the meaning of the other flags, see zshoptions(1). > > WHAT OTHER FLAGS? > The synopsis just says «{+|-}options», with "options" in var() markup. That's unusual: most synopses spell out all valid flags. See for example. That sentence is saying that the flags covered by the mentioned part of the synopsis are documented in zshoptions(1). > So, thanks again for the contribution. Let's try and focus please and the two specific issues identified («set -A» and types; «set -A» and prefixes).