bug#25154: 25.1; Bindings in cl-letf are in reverse order

[Tino Calancha]

Philipp Stephani <p.stephani2@gmail.com> writes:

>  I agree, patches to that effect are welcome.  (AFAICT, the manual
>  tries to say that already, but the wording could be more explicit.)
>
> OK, I've attached a patch that hopefully clarifies this a bit. 
>
> From 42d7450c41d69a713eb8f9492cc169e8c2bc15ca Mon Sep 17 00:00:00 2001
> From: Philipp Stephani <phst@google.com>
> Date: Fri, 23 Dec 2016 13:14:55 +0100
> Subject: [PATCH] Document that variable binding order is unspecified
>
> * doc/lispref/variables.texi (Local Variables):
> * cl.texi (Modify Macros): Document that assignment order in 'let' and
> 'cl-letf' is unspecified.
> ---
>  doc/lispref/variables.texi | 12 ++++++++++++
>  doc/misc/cl.texi           |  5 +++++
>  2 files changed, 17 insertions(+)
>
> diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
> index a2d64815d9..e2c8c542ab 100644
> --- a/doc/lispref/variables.texi
> +++ b/doc/lispref/variables.texi
> @@ -221,6 +221,18 @@ Local Variables
>       @result{} (1 2)
>  @end group
>  @end example
> +
> +On the other hand, the order of @emph{assignments} is unspecified: in
> +the following example, either 1 or 2 might be printed.
> +
> +@example
> +(let ((x 1)
> +      (x 2))
> +  (print x))
> +@end example
> +
> +Therefore, avoid binding a variable more than once in a single
> +@code{let} form.
>  @end defspec
>  
>  @defspec let* (bindings@dots{}) forms@dots{}
> diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
> index c62fa727c1..aa047e2122 100644
> --- a/doc/misc/cl.texi
> +++ b/doc/misc/cl.texi
> @@ -1179,6 +1179,11 @@ Modify Macros
>  as @code{setf} places; each will accept either an integer or a
>  marker as the stored value.)
>  
> +Like in the case of @code{let}, the @var{value} forms are evaluated in
> +the order they appear, but the order of assignments is unspecified.
> +Therefore, avoid assigning to the same @var{place} more than once in a
> +single @code{cl-letf} form.
> +
>  Since generalized variables look like lists, @code{let}'s shorthand
>  of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
>  be ambiguous in @code{cl-letf} and is not allowed.

It looks good to me.  Thank you.
Tino