bug#11862: Splitting and simplifying [PATCH 8/9]

[Michael Witten]

On Fri, 6 Jul 2012 09:45:11 -0700, Drew Adams wrote:

>>> binding is frequently referred to as setting,
>> 
>> This is a bit misleading
>
> I agree.  Binding and setting (assigning) are not the same.
>
> FWIW, here is Common Lisp on "assigning":
> http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node79.html
>
> and on "binding":
> http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node83.html#SECTION001150000000000000000
>
> And there is this, from the book "Successful Lisp":
> http://psg.com/~dlamkins/sl/chapter03-06.html

Yes, that was wrongheaded of me.

I think the best thing to do would be to stick with trivial modifications,
so I've removed the meddling with node `Variables', and then split the
remaining organizational changes into 2 patches:

  [8a/9] Introduce the term `value' early on
  [8b/9] Reduce and reorganize node `A sample Variable Description'

Here is the overall diff (please reply to the relevant patch email):

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 5ca4d37..b62bceb 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -147,10 +147,11 @@ manual.  You may want to skip this section and refer back 
to it later.
   Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
 printer'' refer to those routines in Lisp that convert textual
 representations of Lisp objects into actual Lisp objects, and vice
-versa.  @xref{Printed Representation}, for more details.  You, the
-person reading this manual, are thought of as ``the programmer'' and are
-addressed as ``you''.  ``The user'' is the person who uses Lisp
-programs, including those you write.
+versa.  @xref{Printed Representation}, for more details.  A Lisp object
+is commonly referred to as a @dfn{value}.  You, the person reading this
+manual, are thought of as ``the programmer'' and are addressed as ``you''.
+``The user'' is the person who uses Lisp programs, including those you
+write.
 
 @cindex typographic conventions
   Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
@@ -446,14 +447,9 @@ from @var{body}, which includes all remaining elements of 
the form.
 @cindex variable descriptions
 @cindex option descriptions
 
-  A @dfn{variable} is a name that can hold a value.  Although nearly
-all variables can be set by the user, certain variables exist
-specifically so that users can change them; these are called @dfn{user
-options}.  Ordinary variables and user options are described using a
-format like that for functions except that there are no arguments.
-
-  Here is a description of the imaginary @code{electric-future-map}
-variable.@refill
+Variables are described using a format like that for functions, except
+that there are no arguments.  Here is a description of the imaginary
+@code{electric-future-map} variable.@refill
 
 @defvar electric-future-map
 The value of this variable is a full keymap used by Electric Command
@@ -461,8 +457,10 @@ Future mode.  The functions in this map allow you to edit 
commands you
 have not yet thought about executing.
 @end defvar
 
-  User option descriptions have the same format, but `Variable' is
-replaced by `User Option'.
+Although nearly all variables can be set by the user, certain variables
+exist specifically so that users can change them; these are called
+@dfn{user options}.  User option descriptions have the same format,
+but `Variable' is replaced by `User Option'.
 
 @node Version Info
 @section Version Information
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index ab2789b..b0eea05 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -37,7 +37,7 @@ define them.
 @cindex argument
   In a general sense, a function is a rule for carrying out a
 computation given input values called @dfn{arguments}.  The result of
-the computation is called the @dfn{value} or @dfn{return value} of the
+the computation is called the @dfn{return value} (or the ``value'') of the
 function.  The computation can also have side effects, such as lasting
 changes in the values of variables or the contents of data structures.