GNU bug report logs - #11862
[PATCH 0/9] doc/lispref/intro.texi: Copyediting

Previous Next

Full log

View this message in rfc822 format

From: Michael Witten <mfwitten <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 11862 <at> debbugs.gnu.org, Wolfgang Jenkner <wjenkner <at> inode.at>, Richard Stallman <rms <at> gnu.org>
Subject: bug#11862: Splitting and simplifying [PATCH 8/9]
Date: Fri, 06 Jul 2012 20:06:38 -0000

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.
 

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.