(minor) reader feedback: typos and precisions+

from @E3D3

for #509

time spent: 3 hours.

Author: vindarel

data-structures.md

@@ -340,7 +340,7 @@ Destructuring a plist, giving defaults:
 ~~~lisp
 (destructuring-bind (&key a (b :not-found) c
                      &allow-other-keys)
-    ’(:c 23 :d "D" :a #\A :foo :whatever)
+    '(:c 23 :d "D" :a #\A :foo :whatever)
   (list a b c))
 ;; => (#\A :NOT-FOUND 23)
 ~~~
@@ -462,7 +462,7 @@ Accepts `:test`, `:test-not`, `:key` (functions or symbols).
 ### Replacing objects in a tree: subst, sublis
 
 [subst](http://www.lispworks.com/documentation/HyperSpec/Body/f_substc.htm) and
-`subst-if` search and replace occurences of an element
+`subst-if` search and replace occurrences of an element
 or subexpression in a tree (when it satisfies the optional `test`):
 
 ~~~lisp
@@ -504,52 +504,37 @@ _Note_: see also the [strings](strings.html) page.
 Many of the sequence functions take keyword arguments. All keyword
 arguments are optional and, if specified, may appear in any order.
 
-Pay attention to the `:test` argument. It defaults to `eql` (for
-strings, use `:equal`).
+Pay attention to the `:test` argument. It defaults to `eql`. For
+strings, use `:equal`.
 
-The `:key` argument should be passed either nil, or a function of one
+The `:key` argument can be passed a function of one
 argument. This key function is used as a filter through which the
 elements of the sequence are seen. For instance, this:
 
 ~~~lisp
-(find x y :key 'car)
-~~~
-
-is similar to `(assoc* x y)`: It searches for an element of the list
-whose car equals x, rather than for an element which equals x
-itself. If `:key` is omitted or nil, the filter is effectively the
-identity function.
-
-Example with an alist (see definition below):
+(defparameter *list-of-pairs* '((1 2) (41 42)))
 
-~~~lisp
-(defparameter my-alist (list (cons 'foo "foo")
-                             (cons 'bar "bar")))
-;; => ((FOO . "foo") (BAR . "bar"))
-(find 'bar my-alist)
-;; => NIL
-(find 'bar my-alist :key 'car)
-;; => (BAR . "bar")
+(find 42 *list-of-pairs* :key #'second)
+;; => (41 42)
 ~~~
 
-For more, use a `lambda` that takes one parameter.
+searches for an element in the sequence
+whose `second` element equals 42, rather than for an element which equals 42
+itself. If `:key` is omitted or nil, the filter is effectively the
+`identity` function.
 
-~~~lisp
-(find 'bar my-alist :key (lambda (it) (car it)))
-~~~
-
-~~~lisp
-(find 'bar my-alist :key ^(car %))
-(find 'bar my-alist :key (lm (it) (car it)))
-~~~
+You can use a `lambda` function or any function that accepts one
+argument.
 
 
 ### Predicates: every, some, notany
 
-`every, notevery (test, sequence)`: return nil or t, respectively, as
+`every, notevery (test, sequence)`: they return nil or t, respectively, as
 soon as one test on any set of the corresponding elements of sequences
 returns nil.
 
+`some`, `notany` *(test, sequence)*: they return either the value of the test, or nil.
+
 ~~~lisp
 (defparameter foo '(1 2 3))
 (every #'evenp foo)
@@ -558,18 +543,19 @@ returns nil.
 ;; => T
 ~~~
 
-with a list of strings:
+Example with a list of strings:
 
 ~~~lisp
-(defparameter str '("foo" "bar" "team"))
-(every #'stringp str)
+(defparameter *list-of-strings* '("foo" "bar" "team"))
+(every #'stringp *list-of-strings*)
 ;; => T
-(some (lambda (it) (= 3 (length it))) str)
+
+(some (lambda (it)
+        (= 3 (length it)))
+   *list-of-strings*)
 ;; => T
 ~~~
 
-`some`, `notany` *(test, sequence)*: return either the value of the test, or nil.
-
 
 ### Functions
 
@@ -619,7 +605,7 @@ To this end, use `alexandria-2:subseq*`:
 length of the one to replace.
 
 
-#### sort, stable-sort (sequence, test [, key function])
+#### sort, stable-sort (sequence, test [, key function]) (destructive)
 
 These sort functions are destructive, so one may prefer to copy the sequence with `copy-seq` before sorting:
 
@@ -637,7 +623,7 @@ In theory, the result of this:
 could be either `((1 :A) (1 :B))`, either `((1 :B) (1 :A))`. On my tests, the order is preserved, but the standard does not guarantee it.
 
 
-#### fill (sequence item &keys start end)
+#### fill (sequence item &keys start end) (destructive)
 
 `fill` is a **destructive** operation.
 
@@ -710,11 +696,29 @@ except that all elements equal to `old` are replaced with `new`.
 `nsubstitute` is the non-destructive version.
 
 
-#### sort, stable-sort, merge
+#### merge (result-type, sequence1, sequence2, predicate) (destructive)
 
-(see above)
+The `merge` function is destructive.
 
-#### replace (sequence-a, sequence-b, &key start1, end1)
+> destructively merge `sequence1` with `sequence2` according to an order determined by the predicate.
+
+~~~lisp
+(setq test1 (list 1 3 5 7))
+(setq test2 (list 2 4 6 8))
+(merge 'list test1 test2 #'<)
+;; => (1 2 3 4 5 6 7 8)
+~~~
+
+Now look at `test1`:
+
+~~~lisp
+test1
+;; => (1 2 3 4 5 6 7 8)
+;; at least on SBCL, your result may vary.
+~~~
+
+
+#### replace (sequence-a, sequence-b, &key start1, end1) (destructive)
 
 Destructively replace elements of sequence-a with elements of
 sequence-b.
@@ -727,7 +731,7 @@ The full signature is:
       &key (start1 0) (end1 nil) (start2 0) (end2 nil))
 ~~~
 
-Elements are copied to the subseqeuence bounded by START1 and END1,
+Elements are copied to the subsequence bounded by START1 and END1,
 from the subsequence bounded by START2 and END2. If these subsequences
 are not of the same length, then the shorter length determines how
 many elements are copied.
@@ -764,7 +768,7 @@ see also `remove-if[-not]` below.
 #### remove-duplicates, delete-duplicates (sequence)
 
 [remove-duplicates](http://clhs.lisp.se/Body/f_rm_dup.htm) returns a
-new sequence with uniq elements. `delete-duplicates` may modify the
+new sequence with unique elements. `delete-duplicates` may modify the
 original sequence.
 
 `remove-duplicates` accepts the following, usual arguments: `from-end
@@ -861,9 +865,15 @@ We can use sets functions.
 
 We show below how to use set operations on lists.
 
-A set doesn't contain twice the same element and is unordered.
+A set doesn't contain the same element twice and is unordered.
+
+Most of these functions have recycling (modifying) counterparts,
+starting with "n", e.g.`nintersection` and `nreverse`. The "n" is for
+"non-consing", a lisp parlance for "don't create objects in memory".
 
-Most of these functions have recycling (modifying) counterparts, starting with "n": `nintersection`,… They all accept the usual `:key` and `:test` arguments, so use the test `#'string=` or `#'equal` if you are working with strings.
+They all accept the usual `:key`
+and `:test` arguments, so use the test `#'string=` or `#'equal` if you
+are working with strings.
 
 For more, see functions in
 [Alexandria](https://common-lisp.net/project/alexandria/draft/alexandria.html#Conses):
@@ -889,13 +899,15 @@ What elements are both in list-a and list-b ?
 ;; => (4)
 ~~~
 
-### Join two lists with uniq elements (`union`)
+### Join two lists with unique elements (`union`, `nunion`)
 
 ~~~lisp
 (union list-a list-b)
 ;; => (3 1 0 2 4) ;; order can be different in your lisp
 ~~~
 
+`nunion` is the recycling, destructive version.
+
 ### Remove elements that are in both lists (`set-exclusive-or`)
 
 ~~~lisp
@@ -1071,7 +1083,8 @@ Alists can be used sometimes differently though:
 - they can be easily (de)serialized
 - because of RASSOC, keys and values in alists are essentially
 interchangeable; whereas in hash tables, keys and values play very
-different roles (as usual, see CL Recipes for more).
+different roles (as usual, see "Common Lisp Recipes" by Edmund Weitz
+for more).
 
 
 <a name="create"></a>

emacs-ide.md

@@ -85,10 +85,15 @@ Otherwise, install SLIME by adding this code to your `~/.emacs.d/init.el` file:
 
 ~~~lisp
 (require 'package)
+
 (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
-(dolist (package '(slime))
+
+(defvar my-packages '(slime))
+
+(dolist (package my-packages)
   (unless (package-installed-p package)
     (package-install package)))
+
 (require 'slime)
 ~~~
 
@@ -102,6 +107,12 @@ even the SLIME REPL), you might want to enable more features with
 (slime-setup '(slime-fancy slime-quicklisp slime-asdf slime-mrepl))
 ~~~
 
+Finally, tell Slime to use SBCL:
+
+~~~lisp
+(setq inferior-lisp-program "sbcl")
+~~~
+
 After this you can press Alt-X on your keyboard and type `slime` and try Common Lisp!
 
 (Alt-X is often written `M-x` in Emacs-world.)
@@ -173,7 +184,8 @@ If you can't see it, call `M-x menu-bar-mode RET`.
 
 In the terminal version of Emacs (`emacs -nw`), you can open the menu
 with `M-x menu-bar-open`, which is bound by default to `f10`, or use
-the mouse when it is enabled (`(xterm-mouse-mode +1)`).
+the mouse when it is enabled (evaluate `(xterm-mouse-mode +1)` with
+`M-:` or in the `*scratch*` buffer).
 
 ![](assets/slime-menu.png "Emacs' SLIME menu lists all available commands and keybindings.")
 
@@ -313,7 +325,7 @@ The main shortcut to know is:
 Other bindings which may be useful:
 
 - **C-c C-d f**  describes a function
-- **C-c C-d h**  looks up the symbol documentation in CLHS by opening the web browser. But it works only on symbols, so there are two more bindings:
+- **C-c C-d h**  looks up the symbol documentation in Common Lisp Hyper Spec (CLHS) by opening the web browser. But it works only on symbols, so there are two more bindings:
 - **C-c C-d #** for reader macros
 - **C-c C-d ~**  for format directives
 
@@ -342,7 +354,7 @@ Use `C-c M-m` to macroexpand a macro call
 When you compile and load a file with `C-c C-k` (or a single function
 with `C-c C-c`), and when you have compilation warnings, you don't get
 the interactive debugger. You get the list of warnings inside a
-dedicated "`*slime-compilation*`" buffer that opens up next to your
+dedicated "`*slime-compilation*`" Emacs buffer that opens up next to your
 source file.
 
 Each line of your source impacted by a warning will be underlined in red.
@@ -404,7 +416,7 @@ In Slime, you can use the usual `C-c C-k` in an .asd file to compile and load it
 - `M-x slime-rgrep-system`: run `rgrep` on the base directory of a system.
 - `M-x slime-isearch-system`: run `isearch` on the files of a system.
 - `M-x slime-query-replace-system`: run `query-replace` on an ASDF system.
-- `M-x slime-save-system`: save all files belongign to a system.
+- `M-x slime-save-system`: save all files belonging to a system.
 - `M-x slime-delete-system-fasls`: this deletes the cached .fasl files for this system.
 
 Sly users have a more featureful `sly-load-system` command that will search the .asd file on the current directory and in parent directories.
@@ -879,13 +891,13 @@ Press `C-u M-(` to enclose it with parens:
 
 With a numbered prefix argument (`C-u 2 M-(`), wrap around this number of s-expressions.
 
-Additionnaly, use `M-x check-parens` to spot malformed s-exps.
+Additionally, use `M-x check-parens` to spot malformed s-exps.
 
 There are additional packages that can make your use of parens easier:
 
 - `M-x show-paren-mode`, a built-in Emacs mode: it toggles the visualization of matching parenthesis. When enabled, place the cursor on a paren and you'll see the other paren it matches with. You can initialize it in your Emacs init file with `(show-paren-mode t)`. It is a global minor mode (it will work for all buffers, all languages).
  - **we highly suggest you enable it**.
-- when evil-mode (the vim layer) is enabled, you can use the `%` key to go to the matchin paren.
+- when evil-mode (the vim layer) is enabled, you can use the `%` key to go to the matching paren.
 - `M-x electric-pair-mode`, a built-in Emacs mode: when enabled, typing an open parenthesis automatically inserts the corresponding closing parenthesis, and vice versa.  (Likewise for brackets, etc.). If the region is active, the parentheses (brackets, etc.) are inserted around the region instead.
 - you could use [Paredit (animated guide)](http://danmidwood.com/content/2014/11/21/animated-paredit.html) to automatically insert parentheses in pairs,
 - or [lispy-mode](https://github.com/abo-abo/lispy), like Paredit, but a key triggers an action when the cursor is placed right before or right after a parentheses.
@@ -1054,7 +1066,6 @@ C-c C-o         slime-repl-clear-output
 C-c C-p         slime-repl-previous-prompt
 C-c C-s         slime-complete-form
 C-c C-u         slime-repl-kill-input
-C-c C-z         other-window
 C-c ESC         Prefix Command
 C-c I           slime-repl-inspect
 

functions.md

@@ -34,7 +34,7 @@ Call it:
 ~~~
 
 The `print` function prints its one argument to standard output *and
-returns it*. "hello world" is thus the returned value of our function.
+returns it*. "hello world!" is thus the returned value of our function.
 
 
 ## Arguments
@@ -193,7 +193,7 @@ We saw that a default key parameter is `nil` by default (`(defun hello
 (name &key happy) …)`). But how can be distinguish between "the value
 is NIL by default" and "the user wants it to be NIL"?
 
-We saw how to use a tuple to set its default value:
+We saw how to use a list of two elements to set its default value:
 
 `&key (happy t)`
 
@@ -283,8 +283,7 @@ Common Lisp has also the concept of multiple return values.
 
 ### Multiple return values
 
-Returning multiple values is **not** like returning a tuple or a list of
-results.
+Returning multiple values is **not** like returning a list of results.
 
 #### Quick example
 
@@ -714,7 +713,7 @@ NIL
 ;; We create a variable:
 CL-USER> (defparameter foo 42)
 FOO
-* foo
+CL-USER> foo
 42
 ;; Now foo is "bound":
 CL-USER> (boundp 'foo)
@@ -732,7 +731,7 @@ T
 CL-USER> (function foo)
 #<FUNCTION FOO>
 ;; and the shorthand notation:
-* #'foo
+CL-USER> #'foo
 #<FUNCTION FOO>
 ;; We call it:
 (funcall (function adder) 5)
@@ -751,7 +750,7 @@ The other cell - sometimes referred to as its _function cell_ - can hold the def
 Now, if a _symbol_ is evaluated, it is treated as a _variable_ in that its value cell is returned (just `foo`). If a _compound form_, i.e. a _cons_, is evaluated and its _car_ is a symbol, then the function cell of this symbol is used (as in `(foo 3)`).
 
 
-In Common Lisp, as opposed to Scheme, it is _not_ possible that the car of the compound form to be evaluated is an arbitrary form. If it is not a symbol, it _must_ be a _lambda expression_, which looks like `(lambda `_lambda-list_ _form*_`)`.
+In Common Lisp, as opposed to Scheme, it is _not_ possible that the car of the compound form to be evaluated is an arbitrary form. If it is not a symbol, it _must_ be a _lambda expression_, which looks like `(lambda lambda-list form*)`.
 
 This explains the error message we got above - `(adder 3)` is neither a symbol nor a lambda expression.