bug#25047: Elisp documentation

bug#25047: Elisp documentation

[Bogdan Creanga]

[-- 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.



 

bug#25047: Elisp documentation

[Tino Calancha]

Bogdan Creanga <bogdan.creanga@gmail.com> writes:

>I started to thorougly read the elisp manual, and I noticed some
>possible errors, therefore I attached the file with issues found until
>now.
Thank you very much for your report!
That kind of typos might confuse some readers; it's very
useful catching and fixing them.

;; -----------------------------------------------------------------------
;; node: (elisp) Text Comparison:
;; problem:  duplicate definitions of string-prefix-p and string-suffix-p
Fixed.  Thank you!

;; -----------------------------------------------------------------------
;; node: (elisp) Association Lists
;;  -- Function: alist-get key value &optional default remove
;; problem: in the function header "value" should be replaced with "alist"
This is a known problem; it's already fixed in the trunk version.  Thanks.

;; -----------------------------------------------------------------------
;; node: (elisp) Sequence Functions
;;          (seq-concatenate 'list '(1 2) '(3 4) [5 6])
;;          ⇒ (1 2 3 5 6)
;; problem:  the interger 4 is missing from result
Fixed.  Thank you!

;; -----------------------------------------------------------------------
;; 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)
Fixed.  Thank you!

;; -----------------------------------------------------------------------
;; node: (elisp) Pattern matching case statement
;; problem: the pcase example near the end of page seems not working
;; 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))))

;; 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?
It is mentioned at the beginning that the example requires lexical binding.
If you run the example with `lexical-binding' t, then `evaluate' is
a closure and the example run as expected.

;; -----------------------------------------------------------------------
;; node: (elisp) Generators
;; problem:  generators are not included in elisp.
They are, since 2015 ;-)
M-x: find-library generator RET


Eli, is it OK for you this patch?
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
From 3273ea991b0bc5845f9fa57e9ce229e8188b58e7 Mon Sep 17 00:00:00 2001
From: Bogdan Creanga <bogdan.creanga@gmail.com>
Date: Mon, 28 Nov 2016 12:03:08 +0900
Subject: [PATCH] Typo fixes in elisp manual

* /doc/lispref/sequences.texi: Add missing 4 in result (Bug#25047).
* doc/lispref/strings.texi (Text Comparison): Avoid duplicate
definitions of 'string-prefix-p' and 'string-suffix-p'.
* /doc/lispref/symbols.texi (Definitions): Pluralize 'definitions'.

Copyright-paperwork-exempt: yes
---
 doc/lispref/sequences.texi |  2 +-
 doc/lispref/strings.texi   | 14 --------------
 doc/lispref/symbols.texi   |  2 +-
 3 files changed, 2 insertions(+), 16 deletions(-)

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index a54ab10..9203995 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -832,7 +832,7 @@ Sequence Functions
 @example
 @group
 (seq-concatenate 'list '(1 2) '(3 4) [5 6])
-@result{} (1 2 3 5 6)
+@result{} (1 2 3 4 5 6)
 @end group
 @group
 (seq-concatenate 'string "Hello " "world")
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 5fee373..3069124 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -634,20 +634,6 @@ Text Comparison
 behaves like @code{string-lessp}.
 @end defun
 
-@defun string-prefix-p string1 string2 &optional ignore-case
-This function returns non-@code{nil} if @var{string1} is a prefix of
-@var{string2}; i.e., if @var{string2} starts with @var{string1}.  If
-the optional argument @var{ignore-case} is non-@code{nil}, the
-comparison ignores case differences.
-@end defun
-
-@defun string-suffix-p suffix string &optional ignore-case
-This function returns non-@code{nil} if @var{suffix} is a suffix of
-@var{string}; i.e., if @var{string} ends with @var{suffix}.  If the
-optional argument @var{ignore-case} is non-@code{nil}, the comparison
-ignores case differences.
-@end defun
-
 @defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
 This function compares a specified part of @var{string1} with a
 specified part of @var{string2}.  The specified part of @var{string1}
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 8c1ec3d..36a2795 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -157,7 +157,7 @@ Definitions
 both as a variable (e.g., with @code{defvar}) and as a function or
 macro (e.g., with @code{defun}).  Such definitions do not conflict.
 
-  These definition also act as guides for programming tools.  For
+  These definitions also act as guides for programming tools.  For
 example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers
 containing links to the relevant variable, function, or macro
 definitions.  @xref{Name Help,,, emacs, The GNU Emacs Manual}.
-- 
2.10.2

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
In GNU Emacs 25.1.50.1 (x86_64-pc-linux-gnu, GTK+ Version 3.22.3)
 of 2016-11-27 built on calancha-pc
Repository revision: e46a13446a0dc68e5bc10636d9c40ce5b331efb9

bug#25047: Elisp documentation

[Eli Zaretskii]

> From: Tino Calancha <tino.calancha@gmail.com>
> Cc: Bogdan Creanga <bogdan.creanga@gmail.com>, eliz@gnu.org, tino.calancha@gmail.com
> Date: Mon, 28 Nov 2016 12:17:37 +0900
> 
> Eli, is it OK for you this patch?

In the first issue, the instance to be deleted is the first one, not
the second.  If you look at the Git history, you will clearly see that
what today is the second instance was always there, while the first
one was accidentally added with an unrelated commit.

The other parts are okay, please push this to the emacs-25 branch.

Thanks.

bug#25047: Elisp documentation

[Tino Calancha]

On Mon, 28 Nov 2016, Eli Zaretskii wrote:

> In the first issue, the instance to be deleted is the first one, not
> the second.
OK, thank you.
> The other parts are okay, please push this to the emacs-25 branch.
Pushed into emacs-25 branch as commit: 2086f4c.