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 28967 invoked from network); 22 Dec 2022 13:51:05 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 22 Dec 2022 13:51:05 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20210803; t=1671717065; b=fkF7oq4W0WuLQ0OFDFTPpI9vT8nTsuHC63PJf54a06VFVWh069QsGtS+HtG4cM7ec+1bWhJtby 5cqtCWLr2wzVqEj/vDGVJX2ZjxI0QvInJ/fBAmPrHHwNOBnk/CWo9ZZjkGvMnsY0vOUQbbY5/I ZjBvdPPOVS6+Rm5x196kZCxgKykvnWv+wi9MpIbqKdtTdnZr29qErm/ZSYTw0+LB6bH7FPHodj v28dFXvokkAj0olD0aFfEVC3D99KxBDcqerLa1v2TvIjFJjupSKOssiWGbnHTbmgzhiYxnbVYa lzRcMsMlFw6rcGn1rtuO9x+a9rDDjlEVhT2WNmKZMwFFpg==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (mta02.eastlink.ca) smtp.remote-ip=24.224.136.13; 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=1671717065; bh=uu1m+LZ10CjDHHB+luNifvxDBJ7U0P9o610ApptIN6s=; 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=UAAi2se8c8n8Dki13aFdgp4cvzXiJOgxukBFHwv60+v5XjpdEKMiyUbROLzAaXx9hdVxvn6ruC L+xv7Mo7R7TZixByVtDDXS4ZU3qVoZedI/pdbvdTHj6FplEGv3dum13PWdlAB5KwDnJOGZGeL5 Ua+0W7fT2snnk1LXIMrvyfgns+FCx5uJBLHHWtJZWjJ9wLu2LDurLBuXBTkgWnBPNwl+yeUDOb Qb4l22jkYDat04Y8ulTKSGfCnw56G9YcYjwQLBV6+9mLJ+LUU1YPURihOLWFwu050cztJdgLc1 alNRzy5a+eqzjdo7arWCafiG1fyjVqTnlBFTG/4RKTg6NA==; 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=gHIKaE9ZJszXT7AQTg9r/5a6YqON6nUB2WEfFEUOalI=; b=e0KDvue1T+YQWquKB/NdFBZG9i zHH2S0w0kvsC/XXJcQ/bRDpQRk9PXTdrZ+2oPvt6z86A4CK0k8pGztxQpCpdmrIwqK7Djy21K446J XZePtxliHThXiJeUlawtZViQPF5WcdzvWPTmUgTW1vCvD+HodX2UhvlzMUq/vGzZJZqwSKBjL22yC 17VBhhkiu/on3/5eBl0r/r50UeZ4pe5ZLZzgjypdBTyonIN54nT1gTjgQL91BPKQ+LsIwdnoSCi3X Mv4lo4YIjwNX3ZKz2+1LqRxtDbZXQkovb74WQoN4DPMW2Os52cPGSRv6dcsCPulJtGMvve7VCddF+ YnMXxXJw==; Received: by zero.zsh.org with local id 1p8LyR-0000nu-7P; Thu, 22 Dec 2022 13:51:03 +0000 Authentication-Results: zsh.org; iprev=pass (mta02.eastlink.ca) smtp.remote-ip=24.224.136.13; dmarc=none header.from=eastlink.ca; arc=none Received: from mta02.eastlink.ca ([24.224.136.13]:56506) by zero.zsh.org with esmtps (TLS1.2:ECDHE-RSA-AES128-GCM-SHA256:128) id 1p8Lxc-00006U-M8; Thu, 22 Dec 2022 13:50:13 +0000 Received: from csp02.eastlink.ca ([71.7.199.167]) by mta02.eastlink.ca (Oracle Communications Messaging Server 8.0.2.2.20180531 64bit (built May 31 2018)) with ESMTPS id <0RNA00OWVL0AZZ10@mta02.eastlink.ca> for zsh-users@zsh.org; Thu, 22 Dec 2022 09:50:11 -0400 (AST) Received: from [192.168.0.4] ([24.207.18.108]) by Eastlink with ESMTPSA id 8LxapVy6QeLAh8LxbpddI9; Thu, 22 Dec 2022 09:50:11 -0400 X-Authority-Analysis: v=2.4 cv=S7gfgqgP c=1 sm=1 tr=0 ts=63a46093 a=xN66ZtSbq5jdJYpBp7G/jQ==:117 a=xN66ZtSbq5jdJYpBp7G/jQ==:17 a=IkcTkHD0fZMA:10 a=qS4wVfO9Cx4Cs8ajkfEA:9 a=QEXdDO2ut3YA:10 X-Vade-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedrhedtgdehjecutefuodetggdotefrodftvfcurfhrohhfihhlvgemucfgtefuvffnkffpmfdpqfgfvfenuceurghilhhouhhtmecufedttdenucenucfjughrpefkffggfgfuvfhfhfgjtgfgsehtkeertddtfeejnecuhfhrohhmpeftrgihucetnhgurhgvfihsuceorhgrhigrnhgurhgvfihssegvrghsthhlihhnkhdrtggrqeenucggtffrrghtthgvrhhnpeeitdejffevgfdtheeggfetkeeugeegieetuddtvddvudetteffvdevlefgueekudenucfkphepvdegrddvtdejrddukedruddtkeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepihhnvghtpedvgedrvddtjedrudekrddutdekpdhhvghloheplgduledvrdduieekrddtrdegngdpmhgrihhlfhhrohhmpehrrgihrghnughrvgifshesvggrshhtlhhinhhkrdgtrgdpnhgspghrtghpthhtohepvddprhgtphhtthhopeerredprhgtphhtthhopeiishhhqdhushgvrhhsseiishhhrdhorhhgpdhgvghtqdgkihhprfgrshhsfigupehtrhhuvg X-Vade-Score: 0 X-Vade-State: 0 X-EL-AUTH: rayandrews@eastlink.ca Message-id: <0f445101-6c98-1a7c-277d-e0f5bbb5d460@eastlink.ca> Date: Thu, 22 Dec 2022 05:50:10 -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 Content-language: en-US To: zsh-users@zsh.org References: <71c9c7e9-3f95-143d-fbd6-6575d7f4c446@eastlink.ca> From: Ray Andrews In-reply-to: Content-type: text/plain; charset=UTF-8; format=flowed Content-transfer-encoding: 8bit X-Seq: 28609 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-21 23:03, Lawrence Velázquez wrote: > Partitioning the synopsis isn't a bad idea, but your partition is > misleading because most of the options you separated can actually > be used together in a single "set" command. I'm pleased to have made as few mistakes as I did.  There was no hope that I'd get it right the first time.  It was just a sort of template/sample for my thoughts on how a manual page could be made more useful.  Indeed the way functionalities can be piled on top of each other is why I called 'set' a dog's breakfast.  IMHO we should have setopt (already do), setarray, and setparam.  But I appreciate that set probably got that way by accretion -- over the years stuff got added on and there was no point at which anyone wanted to back out and rethink the thing from the ground up.  London vs. Paris. As you say, a more broken up synopsis -- tho always the better way -- runs into trouble when functionalities can be piled on top of each other but with all sorts of ifs ands buts and maybees  (like the way that '+s' works with '-A' but not with '+A').  It's something to explore how that might be handled.  (Mostly by shaking out the commands themselves!) > POSIX.1-2017 does partition its synopsis [*], but later it has to > explicitly explain that setting and unsetting attributes can be > mixed in a single invocation because the synopsis implies otherwise. > > set [-abCefhmnuvx] [-o option] [argument...] > set [+abCefhmnuvx] [+o option] [argument...] > set -- [argument...] > set -o > set +o Ironically IMHO that's going too far. set [{+,-}abCefhmnuvx] [{+,-}o option] [argument...] ... would be quite tractable. (I myself prefer the comma to the pipe but that's just me.) Dunno, on the one hand I think that manuals should be quite rigid in their use of terminology and the syntax of things like synopses, OTOH there are times when you hafta just 'get it done' -- explain the thing however it needs to be explained and that might mean bending a rule as to synopsis grammar. Interesting questions! But we're out of time anyway. The only real test of/for any doc is whether or not it is useful to the people who might actually need to read it. That means force feeding it to newbies -- the way you force feed medicine to lab rats -- and then asking them if the document is understandable. If it is the doc is good, if not it needs work -- simple as that. I'm trying to be that lab rat. But there are so few of me. > 2): set {+|-}s [STRING] [STRING] ... : > The term "string" is next to useless when discussing shell. Almost > everything is what you might consider a string. That very well could be.  In the world according to Ray, the manual would start with a glossary of terms which would have rigid usage throughout.  Not 'flag' or 'switch' or 'option', pick one and define it exactly and use it exclusively.  Note that even in my experimental run, I took 'option' to mean a switch (cuz it's often used that way) whereas in that case it meant a single letter OPTION -- which is not explained in any way.  One could read that man-page and never know there is any such thing as a single-letter option. > As I already mentioned, this is incorrect. Options and positional > parameters can be mixed in the same invocation. No worries, it was just a dry run.  You're taking it more seriously than I did.  If ever a man-page were to be rewritten by me, it would be subject to checking and editing by knowledgeable people like yourself.  I would never presume to have the final word on anything.  We'd  get it right on the 5th edit.  But I do have a talent for clarity. >> DON'T KNOW WHAT TO DO WITH THAT. > Leave it in? As you would decide.  I'm only saying I myself can't do anything with it. Good writing is a very difficult thing.  Especially good technical writing and coders are notoriously bad at it.