bug#23550: 25.0.93; cl.texi (for var on list by func): Fix documentation

[Tino Calancha]

* doc/misc/cl.texi (for var on list by func): Fix documentation

'cl-loop for var on list by func' behaves as in CL: 'on' expression
need to be a list.

The following tests run in the *scratch* buffer return
same values as in SBCL: 
;; CL cl-loop -> loop

emacs -Q:

(require 'cl-lib)
(setq preys '("grass" "lion" "rabbit"))

(defun next-prey (x)
  "Return the name of the prey of animal X."
  (cl-loop while (not (atom x))
           do (setq x (car x)))
  (cond ((member x preys) ; elisp
  ;; (cond ((member x preys :test #'string=) ; CL
         (cond ((string= x "lion") "rabbit")
               ((string= x "rabbit") "grass")
               (t nil)))
        (t
         nil)))
(defun next-prey-list (x)
  "Return a list with the name of the prey of animal X."
  (let ((res (next-prey x)))
    (if res
        (list res)
      nil)))

[A] (mapcar 'next-prey '("grass" "lion" "rabbit"))
[B] (mapcar 'next-prey-list '("grass" "lion" "rabbit"))

[A] (nil "rabbit" "grass")
[B] (nil ("rabbit") ("grass"))

[I]   (cl-loop for y on preys collect y)
[II]  (cl-loop for y on preys by #'next-prey collect y)
[III] (cl-loop for y on (car preys) by #'next-prey collect y)
[IV]  (cl-loop for y on (car preys) by #'next-prey-list collect y)
[V]   (cl-loop for y on preys by #'next-prey-list collect y)

[I]   (("grass" "lion" "rabbit") ("lion" "rabbit") ("rabbit"))
[II]  (("grass" "lion" "rabbit"))
[III] nil
[IV]  nil
[V]   (("grass" "lion" "rabbit"))


In GNU Emacs 25.0.93.3 (x86_64-pc-linux-gnu, GTK+ Version 2.24.30)
Repository revision: 6de0715f5467d4b925e2dfe082174529ace3b174


> From 3e1756fb4d76e34b74b96782d4509582e9ce0cd3 Mon Sep 17 00:00:00 2001
From: Tino Calancha <f92capac@gmail.com>
Date: Tue, 17 May 2016 00:04:56 +0900
Subject: [PATCH] ; * cl.texi (clause 'for' with 'on'): Fix documentation

---
 doc/misc/cl.texi | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 4137a95..319592c 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1956,18 +1956,6 @@ For Clauses
         @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
 @end example

-With @code{by}, there is no real reason that the @code{on} expression
-must be a list.  For example:
-
-@example
-(cl-loop for x on first-animal by 'next-animal collect x)
-@end example
-
-@noindent
-where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
-the next in the (assumed) sequence of animals, or @code{nil} if
-@var{x} was the last animal in the sequence.
-
 @item for @var{var} in-ref @var{list} by @var{function}
 This is like a regular @code{in} clause, but @var{var} becomes
 a @code{setf}-able ``reference'' onto the elements of the list
--
2.8.1