Re: [PATCH] coding practice in examples (-- with globs mostly)

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Stephane Chazelas wrote on Wed, Jan 01, 2020 at 12:00:09 +0000:
> 2019-12-31 17:16:38 +0000, Daniel Shahaf:
> [...]
> > > {+++ 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.
> 
> I see what you mean. How about something like:
> 
>   zargs -- **/*(.) -- ls -ld --
> 
> The first and third occurrences of -- are used to mark the end
> of options for zargs and ls respectively to guard against
> filenames starting with -, while the second is used to separate
> the list of files from the command to run.
> 
> The first -- would also be needed if there was a chance the list
> might be empty as in:
> 
>   zargs -r -- ./*.back(#qN) -- rm -f

Looks good, thanks.  Please commit.

Further suggestions (nice-to-have's, not blockers):

- Clarify that the third -- isn't syntactically significant, and is just passed
  to ls verbatim.

- Use an example with two --'s before an example with three --'s.

Cheers,

Daniel