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,NICE_REPLY_A,RCVD_IN_DNSWL_MED autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 28417 invoked from network); 21 Dec 2022 04:13:29 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 21 Dec 2022 04:13:29 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20210803; t=1671596009; b=lWFMGdpLRYTVGTTgSWwzZHcePvxVGxOngk7pSiQe7xDouRjyhb5ZwuuQLFFyYeNscrP5cIxumz 0IkaXXusK/AvVmOpIgAGoQlr7o7hRyGCcXSqTb+iyBMwom6ozm0z6etnzWb7qabxP8/GrGjmBI PZeIbJLRB3fEGPhtmbo1m7lQkTTppeiIi17sI8+QNgotPj9C1wDBOdP3oiqbrBF2zEGJaI5FeU 7qXQ8zrFdjyNLrRcqMxhqgJhX5psnnv53ylhaVpQ5QWY8jjriB9NqxXx2ErPxz5Vv+DjBlnlq/ kLZTeiAe0CnKbSr//S4JVZBgizu1s7HMJnN2qAmFcPVYKw==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (mta03.eastlink.ca) smtp.remote-ip=24.224.136.9; dmarc=none header.from=eastlink.ca; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20210803; t=1671596009; bh=B6cO35i9DGAhEYOVAVua6Q+xxBFnm4nKHPatocycpSk=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:Content-Transfer-Encoding:Content-Type:In-Reply-To:From: References:To:Subject:MIME-Version:Date:Message-ID:DKIM-Signature; b=HFlyCA8z2/sN4wDOm0Wgwm850a7bng6/niergOBDsn1hac1+e96tUzL29Qk1J7xMyi8r8zXzey 1CiVT3TjkRbZcXazGfzJnsEn9sRAY+0Ojyf+EevExTDIkAunUQ867TTqArdGXHKrgEY3unvl5q L2MmnS5nmjuVjoW6QyBWxvhJWz32JdksOnY3hVb0AmyxGkCYYA980SuU8BmBENYqTfpAFraGSI kZLVUCTu2zKiXAcFsxtgPFTbKAG4r0/xrkEWrNYsB56EthCP0D/zfkPJxSzyRkn5EUy/jbVeIE 1W/TQixt3n2tS5Gknkj9AJy6wZvweRMUq2tKDERaOiAZFg==; 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:Content-transfer-encoding: Content-type:In-reply-to:From:References:To:Subject:MIME-version:Date: Message-id:Reply-To:Cc:Content-ID:Content-Description:Resent-Date:Resent-From :Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID; bh=0J5rkM0KfCg8KNBt+n9CVVsOAOdsaYTFL6xmWrCCVVA=; b=m7eXwlerzb8dv0SXJmwot0/gVG 0A1MVt6SlH5Z67XvwzluvVQ8yxImaYaHHIhM7JDv2iLVAeq+jYCJ6wNJXU5BhDLriIUcvPdo+3cSX kKUFZ+TsXhPZ1gxpSmZw/RNd40kIEwO+nFbSs9H1L14Fn2VtK+sQTwqTiL/v1vmVtF+x6fmPlgo/G oCnaKFxcyTq/2jSTyzgz0poCxYqK+r1HlLA7JKn+QSiM+lv5urBbYpmQy6vFh+H0avQ4ccS45Masv h9ZENX2HG5xQqjA0xgSDF8Wgh73yhdFer+5cSBIKVR1M28dHpzRjI+P/c8O1m3IPSczez2HfI5e6p iRR+NIgw==; Received: by zero.zsh.org with local id 1p7qTw-000ISS-Fd; Wed, 21 Dec 2022 04:13:28 +0000 Authentication-Results: zsh.org; iprev=pass (mta03.eastlink.ca) smtp.remote-ip=24.224.136.9; dmarc=none header.from=eastlink.ca; arc=none Received: from mta03.eastlink.ca ([24.224.136.9]:43152) by zero.zsh.org with esmtps (TLS1.2:ECDHE-RSA-AES128-GCM-SHA256:128) id 1p7qTF-000Hnw-Ex; Wed, 21 Dec 2022 04:12:46 +0000 Received: from csp02.eastlink.ca ([71.7.199.167]) by mta03.eastlink.ca (Oracle Communications Messaging Server 8.0.2.2.20180531 64bit (built May 31 2018)) with ESMTPS id <0RN8006HQ3JBW162@mta03.eastlink.ca> for zsh-users@zsh.org; Wed, 21 Dec 2022 00:12:44 -0400 (AST) Received: from [192.168.0.4] ([24.207.18.108]) by Eastlink with ESMTPSA id 7qTDpRg7geLAh7qTDpcq5H; Wed, 21 Dec 2022 00:12:44 -0400 X-Authority-Analysis: v=2.4 cv=S7gfgqgP c=1 sm=1 tr=0 ts=63a287bc a=xN66ZtSbq5jdJYpBp7G/jQ==:117 a=xN66ZtSbq5jdJYpBp7G/jQ==:17 a=IkcTkHD0fZMA:10 a=y8W5PRXIqLWXq-GM4pQA:9 a=QEXdDO2ut3YA:10 X-Vade-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedrgeejgdeikecutefuodetggdotefrodftvfcurfhrohhfihhlvgemucfgtefuvffnkffpmfdpqfgfvfenuceurghilhhouhhtmecufedttdenucenucfjughrpefkffggfgfuvfhfhfgjtgfgsehtkeertddtfeejnecuhfhrohhmpeftrgihucetnhgurhgvfihsuceorhgrhigrnhgurhgvfihssegvrghsthhlihhnkhdrtggrqeenucggtffrrghtthgvrhhnpeeitdejffevgfdtheeggfetkeeugeegieetuddtvddvudetteffvdevlefgueekudenucfkphepvdegrddvtdejrddukedruddtkeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepihhnvghtpedvgedrvddtjedrudekrddutdekpdhhvghloheplgduledvrdduieekrddtrdegngdpmhgrihhlfhhrohhmpehrrgihrghnughrvgifshesvggrshhtlhhinhhkrdgtrgdpnhgspghrtghpthhtohepvddprhgtphhtthhopeerredprhgtphhtthhopeiishhhqdhushgvrhhsseiishhhrdhorhhgpdhgvghtqdgkihhprfgrshhsfigupehtrhhuvg X-Vade-Score: 0 X-Vade-State: 0 X-EL-AUTH: rayandrews@eastlink.ca Message-id: <3d9b7820-435d-3bbe-b0ca-67b0f22a19a9@eastlink.ca> Date: Tue, 20 Dec 2022 20:12:43 -0800 MIME-version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.6.0 Subject: Re: manual To: zsh-users@zsh.org References: <71c9c7e9-3f95-143d-fbd6-6575d7f4c446@eastlink.ca> <20221221020026.GH8411@tarpaulin.shahaf.local2> Content-language: en-US From: Ray Andrews In-reply-to: <20221221020026.GH8411@tarpaulin.shahaf.local2> Content-type: text/plain; charset=UTF-8; format=flowed Content-transfer-encoding: 8bit X-Seq: 28601 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: On 2022-12-20 18:00, Daniel Shahaf wrote: > The last sentence goes without saying, for several reasons: Even in the unlikely event that the devs were interested in my writing, it goes without saying that there will be edits. And obviously the devs have the last word on any issue, however: > - 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. It's part of my philosophy to throw in 'helpful hints'.  It's what makes a document actually helpful.  OTOH, as you correctly say, manuals are not focused on that, and in any case it would have to be broadly agreed that any particular helpful hint is really needed.  I needed it, but that's not sufficient. > The assumed knowledge includes the fact that calling any builtin, > function, or external command with anything enclosed in parentheses > would be a syntax error. First I've heard of that!  Seemed to me 'obvious' that there'd be parentheses -- an array is being assigned..  Mind, again, my particular ignorance is no test of what's worth mentioning. > 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.) I need to know more about all that. > Normally the manual would end such a sentence at the comma. Rule > against surplusage, I guess ☺ Yes of course, but it was a first draft!  Actually not even a draft, more like a sample of how I think a manual should be written.  Lots of examples -- actual runnable code that could be pasted to the CL and run.  Break up the synopsis into several lines,  each one covering some specific subset of functionality.  Give some thought to readability.  Remember that people reading the doc are looking for usable information and the test of a doc is that it is helpful to the non-expert.  And so on. > 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. Indeed.  It's clear to me but maybe not to the next guy.  The main thing I was trying to communicate with that little effort is that it's the *example* that makes it clear, not the exposition. > That's unusual: most synopses spell out all valid flags Yes!  Very lazy.  And I took 'options' there to mean option names. Mind, it does actually work that way. > 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). > After you mentioned it, I couldn't stop thinking about it, so had to give it a go.  I was writing it in my dreams last night.