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

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

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