bug#25047: Elisp documentation

[Tino Calancha <tino.calancha@gmail.com>]

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