From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=MAILING_LIST_MULTI, RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from primenet.com.au (ns1.primenet.com.au [203.24.36.2]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id 1d8dc42f for ; Sun, 29 Dec 2019 02:06:26 +0000 (UTC) Received: (qmail 18726 invoked by alias); 29 Dec 2019 02:06:19 -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: X-Seq: 45154 Received: (qmail 2323 invoked by uid 1010); 29 Dec 2019 02:06:19 -0000 X-Qmail-Scanner-Diagnostics: from wout1-smtp.messagingengine.com by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.102.1/25670. spamassassin: 3.4.2. Clear:RC:0(64.147.123.24):SA:0(-2.6/5.0):. Processed in 4.354488 secs); 29 Dec 2019 02:06:19 -0000 X-Envelope-From: d.s@daniel.shahaf.name X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | Received-SPF: none (ns1.primenet.com.au: domain at daniel.shahaf.name does not designate permitted sender hosts) X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedufedrvdefuddggedtucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpeffhffvuffkfhggtggugfgjfgesth ektddttderjeenucfhrhhomhepffgrnhhivghlucfuhhgrhhgrfhcuoegurdhssegurghn ihgvlhdrshhhrghhrghfrdhnrghmvgeqnecukfhppeejledrudektddrheejrdduudelne curfgrrhgrmhepmhgrihhlfhhrohhmpegurdhssegurghnihgvlhdrshhhrghhrghfrdhn rghmvgenucevlhhushhtvghrufhiiigvpedt X-ME-Proxy: Date: Sun, 29 Dec 2019 02:05:34 +0000 From: Daniel Shahaf To: zsh-workers@zsh.org Subject: Re: [Bug] S-flag imposes non-greedy match where it shouldn't Message-ID: <20191229020534.oqh5ri3nqealx4hj@tarpaulin.shahaf.local2> References: <1a130b2e-5824-4b7a-8510-2b1d0b3fdac5@www.fastmail.com> <20191227052923.yal2nnmxdxfgvfkr@tarpaulin.shahaf.local2> <20191228210017.2cdgwgpqrssrfhgp@tarpaulin.shahaf.local2> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: NeoMutt/20170113 (1.7.2) Sebastian Gniazdowski wrote on Sun, Dec 29, 2019 at 01:56:12 +0100: > sob., 28 gru 2019, 22:01 użytkownik Daniel Shahaf > napisał: > > > Sebastian Gniazdowski wrote on Sat, Dec 28, 2019 at 20:04:21 +0100: > > > I think that many examples in the man pages are like that – they don't > > > go the obvious path of just demonstrating the usage but instead, they > > > cover some edge case that, after (sometimes quite long) thinking > > > reveal something very peculiar about the feature. > > > > So what? We're not going to accept a patch that adds an unclear > > explanation > > simply because other explanations are unclear. > > > > I think that the style of the docs has a value. At first one can get little > angry "why the example just doesn't confirm what I already suspect", > however, after untangling it one most probably will feel satisfaction and > gratefulness. It's a way to share advanced, expert knowledge. There should be no untangling. Documentation is about conveying knowledge, not about presenting riddles. The documentation of (S) should explain what (S) does assuming as little knowledge as practicable. Likewise, the documentation of (#b) should, if possible, explain what (#b) does without requiring the reader to know — or, worse, reverse engineer — details such as the greediness of the * operator. That detail should, of course, be documented in the section about that operator. > > You can't actually get rid of the variable $foo; it's needed for the «print» > > call on the next line. > > > Just noticing that this shows another non-trivial aspect of the example - > that it uses mbegin and mend instead of match. Using mbegin and mend is not non-trivial in the context of that example. > > Otherwise, I agree. I'll go ahead and make the change, > > and also change the spaces to underscores. Thanks for pointing this out. > > Do > > you know any other examples that have room for improvement? > > > > As I said I see much value in the current style of the docs and I've > learned much from it, so I don't think it should be changed. Well, I'm sorry, but I expect consensus will not side with you on this. Do you intend to send another revision of the (S) docs patch upthread?