From 70acbfb5807917fbcc55d925495d197edb7bfb4e Mon Sep 17 00:00:00 2001
From: vindarel <vindarel@mailz.org>
Date: Fri, 9 Dec 2022 13:46:29 +0100
Subject: [PATCH] README: system deps, Ultralisp link, can't share a core image

---
 README.org                          | 24 ++++++++++++++++--------
 docs/language-extensions.md         | 12 +++++++-----
 src/more-docstrings/docstrings.lisp |  2 +-
 3 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/README.org b/README.org
index ff4b6c1..174042b 100644
--- a/README.org
+++ b/README.org
@@ -65,7 +65,7 @@ See [[docs/README.md][the documentation]].
 
 - [-] settle on libraries that help newcomers
 - [-] automate the documentation
-- distribute (Quicklisp, Qlot, Quicklisp distribution, Ultralisp,
+- distribute (Quicklisp, Qlot, Quicklisp distribution, [[https://ultralisp.org/projects/ciel-lang/CIEL][Ultralisp]],
   Ultralisp distribution (upcoming)…)
 - [-] ship a binary +and a core image+.
 - optional: create a tool that, given a CIEL code base, explains what
@@ -97,25 +97,32 @@ Rules
 
 * Install
 
+  You will probably need the following system dependencies (names for
+  a Debian system):
+
+: libmagic-dev libc6-dev gcc  # from magicffi
 
 ** With Quicklisp
 
 You need a Lisp implementation and Quicklisp installed.
 
-CIEL is not yet on Quicklisp (but it is on [[https://ultralisp.org][Ultralisp]]), so clone this
-repository and load the .asd (with =load= or =C-c C-k= in
-Slime).
+CIEL is not yet on Quicklisp, but it is on [[https://ultralisp.org][Ultralisp]].
+
+So, either clone this repository:
 
 : git clone https://github.com/ciel-lang/CIEL ~/quicklisp/local-projects/CIEL
 
-Then, quickload it:
+either install the Ultralisp distribution and pull the library from there:
+
+: (ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)
+
+Then, load the .asd file (with =asdf:load-asd= or =C-c C-k= in Slime), quickload "ciel":
 
 #+BEGIN_SRC lisp
 (ql:quickload "ciel")
 #+end_src
 
-and enter the =ciel-user= package, instead of the default
-=common-lisp-user= (or =cl-user=):
+and enter the =ciel-user= package:
 
 #+BEGIN_SRC lisp
 (in-package :ciel-user)
@@ -136,7 +143,8 @@ and use it:
 Then you can configure Slime to have the choice of the Lisp image to
 start. See below in [[*Use CIEL at startup]]
 
-TODO: we will distribute ready-to-use core images.
+We +will distribute ready-to-use core images+ can not distribute core
+images, you must build it yourself.
 
 ** With a binary. Use CIEL's custom REPL.
 
diff --git a/docs/language-extensions.md b/docs/language-extensions.md
index c4720fa..692ed94 100644
--- a/docs/language-extensions.md
+++ b/docs/language-extensions.md
@@ -60,11 +60,13 @@ And there is more. All the available macros are:
 
 We import the `bind` macro from [metabang-bind](https://common-lisp.net/project/metabang-bind/user-guide.html) ([GitHub](https://github.com/gwkkwg/metabang-bind)).
 
-The idiomatic way to declare local variables is `let`. Use it if it is fine for you.
+The idiomatic way to declare local variables is `let` (and `let*`),
+the way to declare local functions is `flet` (and `labels`). Use them
+if it is fine for you.
 
-However, if you ever noticed to write convoluted `let` forms, adding
-list destructuring, multiple values or slot access into the mix, then
-read on.
+However, if you ever noticed you write convoluted `let` forms, adding
+list destructuring, multiple values or slot access into the mix, and
+if you use a `flet` *and then* a `let`, then read on.
 
 `bind` integrates more variable binding and list destructuring idioms. It has two goals. Quoting:
 
@@ -75,7 +77,7 @@ read on.
 ### Bind in CIEL
 
 We import the `bind` macro. However, the package has more external
-symbols that we don't import, such as its error type (`bind-erro`) and
+symbols that we don't import, such as its error type (`bind-error`) and
 its extension mechanism.
 
 > Note: if you like object destructuring in general, you'll like [pattern matching](/language-extensions?id=pattern-matching).
diff --git a/src/more-docstrings/docstrings.lisp b/src/more-docstrings/docstrings.lisp
index 5408710..86a4a14 100644
--- a/src/more-docstrings/docstrings.lisp
+++ b/src/more-docstrings/docstrings.lisp
@@ -155,7 +155,7 @@ eventually be evaluated.
 
 First rule for macros: don't write a macro when a function can do.
 
-Example macros: IF WITH-OPEN-FILE UNWIND-PROTECT DEFUN LOOP
+Example macros: DEFUN LOOP SETF WITH-OPEN-FILE
 
 See also: QUOTE BACKQUOTE GENSYM MACROEXPAND