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 eacc8a6d for ; Tue, 31 Dec 2019 17:17:42 +0000 (UTC) Received: (qmail 12433 invoked by alias); 31 Dec 2019 17:17:31 -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: 45172 Received: (qmail 28812 invoked by uid 1010); 31 Dec 2019 17:17:30 -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/25677. spamassassin: 3.4.2. Clear:RC:0(64.147.123.24):SA:0(-2.6/5.0):. Processed in 11.859791 secs); 31 Dec 2019 17:17:30 -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: gggruggvucftvghtrhhoucdtuddrgedufedrvdefjedgleeiucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpeffhffvuffkfhggtggugfgjfgesth ektddttderudenucfhrhhomhepffgrnhhivghlucfuhhgrhhgrfhcuoegurdhssegurghn ihgvlhdrshhhrghhrghfrdhnrghmvgeqnecukfhppeejledrudektddrheejrdduudelne curfgrrhgrmhepmhgrihhlfhhrohhmpegurdhssegurghnihgvlhdrshhhrghhrghfrdhn rghmvgenucevlhhushhtvghrufhiiigvpedt X-ME-Proxy: Date: Tue, 31 Dec 2019 17:16:38 +0000 From: Daniel Shahaf To: Zsh hackers list Subject: Re: [PATCH] coding practice in examples (-- with globs mostly) Message-ID: <20191231171638.en6olco722w4ldcc@tarpaulin.shahaf.local2> References: <20191231091618.v2erkblkwkiy3i5a@chaz.gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20191231091618.v2erkblkwkiy3i5a@chaz.gmail.com> User-Agent: NeoMutt/20170113 (1.7.2) Stephane Chazelas wrote on Tue, Dec 31, 2019 at 09:16:18 +0000: > Hello, I've spotted a few cases in the doc of things like "ls *" > instead of "ls -d -- *". > > While that's something one could do interactively when they know > how the files are named and their nature, that's bad practice in > scripts. As a reference manual, IMO, the zsh documentation > should show "the right way". +1 and thanks for the patch. Two small suggestions: > {+++ b/Doc/Zsh/builtins.yo+} > @@ -1258,7 +1258,11 @@ If given together with tt(-o) or tt(-O), sorting is performed > item(tt(-l))( > -Print the arguments separated by newlines instead of spaces. > +Print the arguments separated by newlines instead of spaces. Note: > +if the list of arguments is empty, tt(print -l) as opposed to > +tt(print -C1), still outputs one empty line; tt(print -rC1 -- > +"$list[@]") is a more canonical way to print an arbitrary list of > +arguments, one per line. Suggest not to mention the solution before the problem: +Note: if the list of arguments is empty, tt(print -l) will still output one +empty line. To print a possibly-empty list of arguments one per line, use +tt(print -C1), as in `tt(print -rC1 -- "$list[@]")'. > {+++ b/Doc/Zsh/contrib.yo+} > @@ -4422,10 +4422,11 @@ For example, to get a long tt(ls) listing of all plain files in the > current directory or its subdirectories: > > example(autoload -U zargs > zargs -- **/*(.) -- ls [--l)-] {+-ld --)+} > > Note that `tt(-)tt(-)' is used both to mark the end of the var(option) > list and to mark the end of the var(input) [-list,-] {+list (and here also to mark > the end of the option list for tt(ls)),+} so it must appear twice > whenever the var(input) list may be empty. If there is guaranteed to be > at least one var(input) and the first var(input) does not begin with a > `tt(-)', then the first `tt(-)tt(-)' may be omitted. I think the text could be a little hard to follow, since there are three «--» but it talks about "both" and then mentions the third in an afterthought. Would you prefer to change the incumbent text as well? You're not limited to adding parentheticals. Cheers, Daniel