bug#25047: Elisp documentation

[Bogdan Creanga <bogdan.creanga@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 399 bytes --]

Hello there,

I'm using emacs version:
GNU Emacs 25.1.1 (x86_64-w64-mingw32) of 2016-09-22

I started to thorougly read the elisp manual, and I noticed some
possible errors, therefore I attached the file with issues found until
now.  Briefly, there are some insignificant errors, the generators
apparently missing from emacs, and there is a problem with a `pcase'
example.

Than you,
Bogdan Creanga

[-- Attachment #2: errata-emacs.txt --]
[-- Type: text/plain, Size: 5132 bytes --]

; -*- mode: lisp-interaction; -*-



;; GNU Emacs 25.1.1 (x86_64-w64-mingw32) of 2016-09-22



;; ELISP MANUAL ERRATA:


;; -----------------------------------------------------------------------
;; node: (elisp) Text Comparison:
;; problem:  duplicate definitions of string-prefix-p and string-suffix-p

;; -----------------------------------------------------------------------
;; node: (elisp) Association Lists
;;  -- Function: alist-get key value &optional default remove
;;      This function is like ‘assq’, but instead of returning the entire
;;      association for KEY, ‘(KEY . VALUE)’, it returns just the VALUE.
;;      If KEY is not found in ALIST it returns DEFAULT.
;; 
;; problem: in the function header "value" should be replaced with "alist"
;; as it might be noticed in the defun:
;; (defun alist-get (key alist &optional default remove)
;;    "Return the value associated with KEY in ALIST, using `assq'.
;;     If KEY is not found in ALIST, return DEFAULT.  [...]

;; -----------------------------------------------------------------------
;; node: (elisp) Sequence Functions
;; -- Function: seq-concatenate type &rest sequences
;;     This function returns a sequence of type TYPE made of the
;;     concatenation of SEQUENCES.  TYPE may be: ‘vector’, ‘list’ or
;;     ‘string’.
;;
;;          (seq-concatenate 'list '(1 2) '(3 4) [5 6])
;;          ⇒ (1 2 3 5 6)
;; problem:  the interger 4 is missing from result


;; -----------------------------------------------------------------------
;; node: (elisp) Definitions
;;    These definition also act as guides for programming tools.  For
;; example, the ‘C-h f’ and ‘C-h v’ commands create help buffers containing
;; links to the relevant variable, function, or macro definitions.  *Note
;; (emacs)Name Help::.
;;
;; problem: It is written: "These definition", should be "These definitions"
;; (plural)


;; -----------------------------------------------------------------------
;; node: (elisp) Pattern matching case statement
;; problem: the pcase example near the end of page seems not working
;; here we have the original definition:
(defun evaluate (exp env)
  (pcase exp
    (`(add ,x ,y)       (+ (evaluate x env) (evaluate y env)))
    (`(call ,fun ,arg)  (funcall (evaluate fun env) (evaluate arg env)))
    (`(fn ,arg ,body)   (lambda (val)
                          (evaluate body (cons (cons arg val) env))))
    ((pred numberp)     exp)
    ((pred symbolp)     (cdr (assq exp env)))
    (_                  (error "Unknown expression %S" exp))))

;; here we have the working definition, see embedded comment 
(defun evaluate-q-added (exp env)
  (pcase exp
    (`(add ,x ,y)       (+ (evaluate-q-added x env) (evaluate-q-added y env)))
    (`(call ,fun ,arg)  (funcall (evaluate-q-added fun env) (evaluate-q-added arg env)))
    ;; modified case, added quotes to lambda expression, and body and argf
    (`(fn ,argf ,body)  `(lambda (val)
                           (evaluate-q-added ',body (cons (cons ',argf val) env)))) 
    ((pred numberp)     exp)
    ((pred symbolp)     (cdr (assq exp env)))
    (_                  (error "Unknown expression %S" exp))))

;; here we have the manual examples run for each version;  the original version first:
(evaluate '(add 1 2) nil)                  ;=> 3
(evaluate '(add x y) '((x . 1) (y . 2)))   ;=> 3
(evaluate '(call (fn x (add 1 x))  2) nil) ;=! NOT OK: 
   ;; ;; Debugger entered--Lisp error: (void-variable body)
   ;; ;;   (evaluate body (cons (cons arg val) env))
   ;; ;;   (lambda (val) (evaluate body (cons (cons arg val) env)))(2)
   ;; ;;   funcall((lambda (val) (evaluate body (cons (cons arg val) env))) 2)
   ;; ;;   (let ((arg x) (fun x)) (funcall (evaluate fun env) (evaluate arg env)))
   ;; ;; 
(evaluate '(sub 1 2) nil)                  ;=! OK: Debugger
                                           ;entered--Lisp error:
                                           ;(error "Unknown expression
                                           ;(sub 1 2)")

;; the "fixed one"
(evaluate-q-added '(add 1 2) nil)                  ;=> 3
(evaluate-q-added '(add x y) '((x . 1) (y . 2)))   ;=> 3
(evaluate-q-added '(call (fn x (add 1 x))  2) nil) ;=> 3
(evaluate-q-added '(sub 1 2) nil)                  ;=! OK: Debugger
                                                   ;entered--Lisp
                                                   ;error: (error
                                                   ;"Unknown
                                                   ;expression (sub 1
                                                   ;2)")

;; I made the code change by "intuition", for me is the first time I
;; see this kind of construct ( ',object ); is this correct?  Is
;; lambda expression right about NOT substituting the expanded body
;; but taking in place the lexical name?



;; -----------------------------------------------------------------------
;; node: (elisp) Generators
;; problem:  generators are not included in elisp.