bug#32803: 26.1.50; cl-do: Add more literature in docstring

[Tino Calancha]

On Mon, 24 Sep 2018, Eric Abrahamsen wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
> > > From: Eric Abrahamsen <eric@ericabrahamsen.net>
> > > Cc: Eli Zaretskii <eliz@gnu.org>,  32803@debbugs.gnu.org
> > > Date: Mon, 24 Sep 2018 09:43:49 -0700
> > >
> > > > +Then, in each iteration of the loop, the END-TEST is evaluated; if true,
> > >          ^^^^^^^
> > >
> > > > From the peanut gallery: Without looking at the code, I'm not sure if
> > > this means the test is evaluated *before* BODY (ie, BODY may never run),
> > > or *after* BODY (ie, BODY always runs at least once).
> >
> > You've removed the answer to that question.  The full text says:
> >
> >                                                           Then, in each
> >      iteration of the loop, the END-TEST is evaluated; if true, the loop
> >      is finished.  Otherwise, the body FORMS are evaluated, then each
> >      VAR is set to the associated STEP expression [...]
> >
> > which clearly tells that the test is done _before_ the BODY is run.
> > Right?
>
> I guess you're right, yes. "In" still seems unnecessarily vague, though,
> when it could simply be replaced with "before". But not that big a deal,
> I guess.
Thank you for the feedback Eric.
In some sense, the endtest is part of the loop, that's why the "in".
It behaves similar like this:

[initialize/update VARS]
(if endtest
  (return RESULT)
 body)


I am OK to rephrase it to make it more obvious if you have something
in mind.
Some people learning CL complaint about this iteration as been weird.
I see it as a generalization of a `dolist'.  Paul Graham build many tools
on top of this.