Re: [PATCH] zshmisc(1): document implicit append of `term` when `in word` is omitted

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Joey Pabalinas wrote on Sat, Dec 15, 2018 at 16:01:27 -1000:
> On Sun, Dec 16, 2018 at 01:53:10AM +0000, Daniel Shahaf wrote:
> > Joey Pabalinas wrote on Sat, 15 Dec 2018 10:26 -1000:
> > > This is fairly innocuous behavior and is POSIX-compliant, so document
> > > this odd edge case rather than risk regressions attempting to change
> > > the lexer/parser code.
> > 
> > If preventing regressions is your goal, why not add a regression test using this syntax?
> 
> Sorry, maybe my commit message was a bit unclear. I meant instead of
> trying to poke at the parser/lexer code to make the behavior match the
> documentation, I figured it's easier to just do it the other way and
> document the weird edge case.
> 
> Sorry for the ambiguity (and the double send, forgot to CC the list),

The double send is my fault, not yours.  It is I who replied off-list in
the first place.

> should I revise the commit description?

Let me begin by saying I'm not familiar enough with the parser to have
an opinion on whether it would be better to have change the docs to
match the code, or change the code to match the docs, or leave this as
an implementation detail that's subject to change.

All that said, I'm not too bothered by the grammar of the log message
(which is now explained in this thread anyway).  I'd sooner suggest
changes to the new text:

> +++ b/Doc/Zsh/grammar.yo
> @@ -185,11 +185,12 @@ cindex(loops, for)
>  item(tt(for) var(name) ... [ tt(in) var(word) ... ] var(term) tt(do) var(list) tt(done))(
>  where var(term) is at least one newline or tt(;).
>  Expand the list of var(word)s, and set the parameter
>  var(name) to each of them in turn, executing
>  var(list) each time.  If the tt(in) var(word) is omitted,
> -use the positional parameters instead of the var(word)s.
> +use the positional parameters with a var(term) implicitly
> +appended instead of the var(word)s.
>  

Two issues here:

1. The docs of var(term) are spread across the first and last sentence.

2. Adding a side remark about var(term) to the last sentence may obscure
that sentence's primary point about the fallback to positional
parameters.

So, perhaps something like this (relative to master):

-where var(term) is at least one newline or tt(;).
 Expand the list of var(word)s, and set the parameter
 var(name) to each of them in turn, executing
-var(list) each time.  If the tt(in) var(word) is omitted,
+var(list) each time.  If the `tt(in) var(word)' is omitted,
 use the positional parameters instead of the var(word)s.
+
+var(term) should be one or more newline or tt(;), and is optional if
+the `tt(in) var(word)' is omitted.

But let's wait for someone familiar with the parser to opine on the
proposed strategic direction ("document the parser's behaviour") before
we spend too much time on implementing that.

>  More than one parameter var(name) can appear before the list of
>  var(word)s.  If var(N) var(name)s are given, then on each execution of the
>  loop the next var(N) var(word)s are assigned to the corresponding
>  parameters.  If there are more var(name)s than remaining var(word)s, the

Cheers,

Daniel