From b56c9c12bee88dda4d2292fb69910648fd14bae4 Mon Sep 17 00:00:00 2001
From: Marius Gerbershagen <marius.gerbershagen@gmail.com>
Date: Sun, 24 Jun 2018 15:39:57 +0200
Subject: [PATCH] doc: fix section about the interpreter lexical environment

---
 .../new-doc/developer-guide/interpreter.txi   | 33 ++++++++++++-------
 src/doc/new-doc/developer-guide/objects.txi   |  6 ++--
 2 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/src/doc/new-doc/developer-guide/interpreter.txi b/src/doc/new-doc/developer-guide/interpreter.txi
index 0ccf101e5..e664448e4 100644
--- a/src/doc/new-doc/developer-guide/interpreter.txi
+++ b/src/doc/new-doc/developer-guide/interpreter.txi
@@ -1,6 +1,14 @@
 @node The interpreter
 @section The interpreter
 
+@menu
+* ECL stacks::
+* Procedure Call Conventions::
+* The lexical environment::
+* The interpreter stack::
+@end menu
+
+@node ECL stacks
 @subsection ECL stacks
 ECL uses the following stacks:
 @multitable @columnfractions .3 .7
@@ -14,6 +22,7 @@ ECL uses the following stacks:
 @tab used for arguments/values passing, typed lexical variables, temporary values, and function invocation.
 @end multitable
 
+@node Procedure Call Conventions
 @subsection Procedure Call Conventions
 ECL employs standard C calling conventions to achieve efficiency and
 interoperability with other languages. Each Lisp function is
@@ -69,20 +78,22 @@ instance, the actual source code for @code{cl_cons} in
 @)
 @end verbatim
 
+@node The lexical environment
 @subsection The lexical environment
-The ECL interpreter uses two A-lists (Association lists) to represent
-lexical environments.
-
-@itemize
-@item One for variable bindings
-@item One for local function/macro/tag/block bindings
-@end itemize
-
-When a function closure is created, the current two A-lists are saved
-in the closure along with the lambda expression. Later, when the
-closure is invoked, the saved A-lists are used to recover the lexical
+The ECL interpreter uses a list containing local functions and macros,
+variables, tags and blocks to represent the lexical environment. When
+a function closure is created, the current lexical environment is
+saved in the closure along with the lambda expression. Later, when the
+closure is invoked, this list is used to recover the lexical
 environment.
 
+Note that this list is different from what the Common Lisp standard
+calls a lexical environment, which is the content of a
+@code{&environment} parameter to @code{defmacro}. For the differences
+between this two environments see the comments in
+@code{src/c/compiler.d} and @code{src/c/interpreter.d}.
+
+@node The interpreter stack
 @subsection The interpreter stack
 
 The bytecodes interpreter uses a stack of its own to save and restore
diff --git a/src/doc/new-doc/developer-guide/objects.txi b/src/doc/new-doc/developer-guide/objects.txi
index c31b89427..1173e0b08 100644
--- a/src/doc/new-doc/developer-guide/objects.txi
+++ b/src/doc/new-doc/developer-guide/objects.txi
@@ -756,7 +756,9 @@ make_lambda function.
 @cppindex cl_eval
 @deftypefun cl_object si_safe_eval (cl_object form, cl_object env, ...)
 
-@code{si_safe_eval} evaluates @code{form} in the lexical environment
+@code{si_safe_eval} evaluates @code{form} in the lexical
+environment@footnote{Note that @code{env} must be a lexical
+environment as used in the interpreter, @xref{The lexical environment}}
 @code{env}, which can be @var{ECL_NIL}. Before evaluating it, the
 expression form must be bytecompiled.
 
@@ -769,7 +771,7 @@ compatibility with previous versions.
 Equivalent of @code{si_safe_eval} (macro define).
 @end table
 
-@subheading Exmaple
+@subheading Example
 @exindex @code{cl_safe_eval}
 @example
 si_object form = c_string_to_object("(print 1)");