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

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

[Michael Witten]

Whilst reading through the Emacs Lisp reference (specifically intro.texi),
I did some copyediting, which resulted in the following patch series:

  doc/lispref/intro.texi | 36 ++++++++++++++++++++----------------
  1 file changed, 20 insertions(+), 16 deletions(-)

  [1] Offset modifier with a comma
  [2] `can' -> `may'
  [3] Eradicate that pesky future tense
  [4] More precise language about argument types
  [5] Use singular form in a sentence
  [6] Re-fill a paragraph
  [7] `optional' -> `&optional'; `rest' -> `&rest'
  [8] More precise language for what a variable is
  [9] Use passive voice

Patches [4], [5], and [6] could be squashed together if that is
desirable

Sincerely,
Michael Witten

-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma

[Michael Witten]

---
 doc/lispref/intro.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 841cfac..212e604 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -235,7 +235,7 @@ evaluation of the expanded form.
      @result{} c
 @end example
 
-  Sometimes to help describe one form we show another form that
+  Sometimes to help describe one form, we show another form that
 produces identical results.  The exact equivalence of two forms is
 indicated with @samp{@equiv{}}.
 
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 2/9] doc/lispref/intro.texi: `can' -> `may'

[Michael Witten]

---
 doc/lispref/intro.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 212e604..273945c 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -350,7 +350,7 @@ arguments default to @code{nil}).  Do not write @code{&optional} when
 you call the function.
 
   The keyword @code{&rest} (which must be followed by a single
-argument name) indicates that any number of arguments can follow.  The
+argument name) indicates that any number of arguments may follow.  The
 single argument name following @code{&rest} will receive, as its
 value, a list of all the remaining arguments passed to the function.
 Do not write @code{&rest} when you call the function.
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense

[Michael Witten]

Universal and eternal truths are better represented with the
present tense.
---
 doc/lispref/intro.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 273945c..4f0f8cd 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -351,7 +351,7 @@ you call the function.
 
   The keyword @code{&rest} (which must be followed by a single
 argument name) indicates that any number of arguments may follow.  The
-single argument name following @code{&rest} will receive, as its
+single argument name following @code{&rest} receives, as its
 value, a list of all the remaining arguments passed to the function.
 Do not write @code{&rest} when you call the function.
 
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language

[Michael Witten]

When a type is specified in the description of a function's argument, it
is the object to which that argument is bound (rather than the argument
itself) that is expected to be of that type; this is a bit pedantic,
but, hey! This is a reference manual.

(The paragraph should be re-filled by a future commit.)
---
 doc/lispref/intro.texi | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 4f0f8cd..50e6712 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -380,9 +380,11 @@ More generally,
 @end defun
 
   Any argument whose name contains the name of a type (e.g.,
-@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
+@var{integer}, @var{integer1} or @var{buffer}) is expected to be
+bound to an object of that
 type.  A plural of a type (such as @var{buffers}) often means a list of
-objects of that type.  Arguments named @var{object} may be of any type.
+objects of that type.  An argument named with the type @var{object} may be
+bound to an object of any type.
 (@xref{Lisp Data Types}, for a list of Emacs object types.)  Arguments
 with other sorts of names (e.g., @var{new-file}) are discussed
 specifically in the description of the function.  In some sections,
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 5/9] doc/lispref/intro.texi: Use singular form in a sentence

[Michael Witten]

It's often more precise to describe the general case by using
a singular subject.

(The paragraph should be re-filled by a future commit.)
---
 doc/lispref/intro.texi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 50e6712..a5a9747 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -385,8 +385,8 @@ bound to an object of that
 type.  A plural of a type (such as @var{buffers}) often means a list of
 objects of that type.  An argument named with the type @var{object} may be
 bound to an object of any type.
-(@xref{Lisp Data Types}, for a list of Emacs object types.)  Arguments
-with other sorts of names (e.g., @var{new-file}) are discussed
+(@xref{Lisp Data Types} for a list of Emacs object types.)  An argument
+with some other sort of name (e.g., @var{new-file}) is discussed
 specifically in the description of the function.  In some sections,
 features common to the arguments of several functions are described at
 the beginning.
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 6/9] doc/lispref/intro.texi: Re-fill a paragraph

[Michael Witten]

Some previous commits altered the text in a way that left this
particular paragraph with some rather unfortunately placed
hard newlines. This commit undoes that damage.
---
 doc/lispref/intro.texi | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index a5a9747..f680688 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -380,11 +380,10 @@ More generally,
 @end defun
 
   Any argument whose name contains the name of a type (e.g.,
-@var{integer}, @var{integer1} or @var{buffer}) is expected to be
-bound to an object of that
-type.  A plural of a type (such as @var{buffers}) often means a list of
-objects of that type.  An argument named with the type @var{object} may be
-bound to an object of any type.
+@var{integer}, @var{integer1} or @var{buffer}) is expected to be bound
+to an object of that type.  A plural of a type (such as @var{buffers})
+often means a list of objects of that type.  An argument named with the
+type @var{object} may be bound to an object of any type.
 (@xref{Lisp Data Types} for a list of Emacs object types.)  An argument
 with some other sort of name (e.g., @var{new-file}) is discussed
 specifically in the description of the function.  In some sections,
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 7/9] doc/lispref/intro.texi: `optional' -> `&optional';

[Michael Witten]

In particular, the word `rest' as used in the original text is quite
jarring to read, so the more explicit `&rest' is introduced by this
commit. For completeness, the word `optional' is likewise replaced
with `&optional'.

Also, a spurious comma after the cross reference has been removed,
and the word ordering rearranged for simplicity.
---
 doc/lispref/intro.texi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index f680688..f749401 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -390,8 +390,8 @@ specifically in the description of the function.  In some sections,
 features common to the arguments of several functions are described at
 the beginning.
 
-  @xref{Lambda Expressions}, for a more complete description of optional
-and rest arguments.
+  @xref{Lambda Expressions} for a more complete description of arguments
+modified by @code{&optional} and @code{&rest}.
 
   Command, macro, and special form descriptions have the same format,
 but the word `Function' is replaced by `Command', `Macro', or `Special
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for

[Michael Witten]

The terms `set' and `bind', `object' and `value', and `hold' are used
somewhat freely; a previous commit already prefers `bind' and `object',
so this commit refines the text for the definition of a variable to
prefer those too (while still mentioning the others).
---
 doc/lispref/intro.texi | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index f749401..a68e7a9 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -446,11 +446,14 @@ 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.
+  A @dfn{variable} is a name that can be bound to an object; binding
+is frequently referred to as `setting', and the object to which
+a variable is `set' is often called a `value' that the variable
+`holds'.  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
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice

[Michael Witten]

There's no value in using `you' as the subject here, especially given
that the surrounding text doesn't do so.
---
 doc/lispref/intro.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index a68e7a9..da39375 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -508,7 +508,7 @@ emacs-build-time
 The value of this variable is the version of Emacs being run.  It is a
 string such as @code{"23.1.1"}.  The last number in this string is not
 really part of the Emacs release version number; it is incremented
-each time you build Emacs in any given directory.  A value with four
+each time Emacs is built in any given directory.  A value with four
 numeric components, such as @code{"22.0.91.1"}, indicates an
 unreleased test version.
 @end defvar
-- 
1.7.11.1.29.gf71be5c

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

[Stefan Monnier]

> Whilst reading through the Emacs Lisp reference (specifically intro.texi),
> I did some copyediting, which resulted in the following patch series:

Thank you, installed,


        Stefan

bug#11862: [PATCH 7/9] doc/lispref/intro.texi: `optional' -> `&optional';

[Glenn Morris]

Michael Witten wrote:

> Also, a spurious comma after the cross reference has been removed,

It was not spurious.

doc/lispref/intro.texi:387: warning: `.' or `,' must follow @xref, not `f'.
doc/lispref/intro.texi:393: warning: `.' or `,' must follow @xref, not `f'.

> -  @xref{Lambda Expressions}, for a more complete description of optional
> -and rest arguments.
> +  @xref{Lambda Expressions} for a more complete description of arguments
> +modified by @code{&optional} and @code{&rest}.

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

[Glenn Morris]

It's ok, I already installed a correction (I should have said).

bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma

[Richard Stallman]

    -  Sometimes to help describe one form we show another form that
    +  Sometimes to help describe one form, we show another form that
     produces identical results.

An unpaired comma here is not correct.
This would be correct

    +  Sometimes, to help describe one form, we show another form that

or this

    +  To help describe one form, we sometimes show another form that

However, the current text is also correct; commas here are not
required.

--
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#11862: [PATCH 2/9] doc/lispref/intro.texi: `can' -> `may'

[Richard Stallman]

       The keyword @code{&rest} (which must be followed by a single
    -argument name) indicates that any number of arguments can follow.  The
    +argument name) indicates that any number of arguments may follow.

The old text is correct.  Replacing it with "may" is not wrong, but it
adds a formality that we try to avoid in GNU manuals.

So please don't make this change.

--
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense

[Richard Stallman]

    Universal and eternal truths are better represented with the
    present tense.

That's right.

--
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language

[Richard Stallman]

       Any argument whose name contains the name of a type (e.g.,
    -@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
    +@var{integer}, @var{integer1} or @var{buffer}) is expected to be
    +bound to an object of that
     type.

We normally use "argument" to refer to the value, not the name.
Thus, it is correct as written now.  Please don't make it more pedantic.

--
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice

[Richard Stallman]

     The value of this variable is the version of Emacs being run.  It is a
     string such as @code{"23.1.1"}.  The last number in this string is not
     really part of the Emacs release version number; it is incremented
    -each time you build Emacs in any given directory.  A value with four
    +each time Emacs is built in any given directory.

Please use the active voice by preference.
For instance, you could write it this:

   each time you build Emacs in a given directory, that increments this number.

--
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice

[Stephen Berman]

On Thu, 05 Jul 2012 06:14:00 -0400 Richard Stallman <rms@gnu.org> wrote:

>      The value of this variable is the version of Emacs being run.  It is a
>      string such as @code{"23.1.1"}.  The last number in this string is not
>      really part of the Emacs release version number; it is incremented
>     -each time you build Emacs in any given directory.  A value with four
>     +each time Emacs is built in any given directory.
>
> Please use the active voice by preference.
> For instance, you could write it this:
>
>    each time you build Emacs in a given directory, that increments this number.

This sounds rather awkward to me.  Would you accept "it gets
incremented" as a "more active passive" alternative?  Aside from style,
the statement is inaccurate, isn't it?  At least with "make bootstrap"
the last number is always 1.

Steve Berman

bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Date: Thu, 05 Jul 2012 16:04:22 +0200
> Cc: 11862@debbugs.gnu.org
> 
> On Thu, 05 Jul 2012 06:14:00 -0400 Richard Stallman <rms@gnu.org> wrote:
> 
> >      The value of this variable is the version of Emacs being run.  It is a
> >      string such as @code{"23.1.1"}.  The last number in this string is not
> >      really part of the Emacs release version number; it is incremented
> >     -each time you build Emacs in any given directory.  A value with four
> >     +each time Emacs is built in any given directory.
> >
> > Please use the active voice by preference.
> > For instance, you could write it this:
> >
> >    each time you build Emacs in a given directory, that increments this number.
> 
> This sounds rather awkward to me.  Would you accept "it gets
> incremented" as a "more active passive" alternative?

I think there's a better alternative that is entirely active:

  each build of Emacs in any given directory increments that number.

> Aside from style, the statement is inaccurate, isn't it?  At least
> with "make bootstrap" the last number is always 1.

Yes.  So:

   The value of this variable is the version of Emacs being run.  It
   is a string such as @code{"23.1.1"}.  The last number in this
   string is not really part of the Emacs release version number; it
   starts at 1, is reset to 1 by @kbd{make bootstrap}, and each build
   of Emacs increments that number.

bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier

[Michael Witten]

On Thu, 05 Jul 2012 06:13:55 -0400, Richard Stallman wrote:

>     -  Sometimes to help describe one form we show another form that
>     +  Sometimes to help describe one form, we show another form that
>      produces identical results.
> 
> An unpaired comma here is not correct.
> This would be correct
> 
>     +  Sometimes, to help describe one form, we show another form that
> 
> or this
> 
>     +  To help describe one form, we sometimes show another form that
> 
> However, the current text is also correct; commas here are not
> required.

I prefer your second suggestion above all else.

bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice

[Glenn Morris]

>> Aside from style, the statement is inaccurate, isn't it?  At least
>> with "make bootstrap" the last number is always 1.

I don't think the lispref needs to worry about these details.
(Plain `make clean' causes the same result; it seems kind of obvious to
me...).

bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice

[Michael Witten]

On Thu, 05 Jul 2012 19:37:55 +0300, Eli Zaretskii <eliz@gnu.org> wrote:

> it starts at 1, is reset to 1 by @kbd{make bootstrap}, and each build
> of Emacs increments that number.

In all clauses but the last, `it' (that is, the last number) is the subject.
Moroever, the middle clause is already in the passive voice. So, for the sake of
consistency, why not continue with both the subject `it' and that passive voice:

  it starts at 1, is reset to 1 by @kbd{make bootstrap}, and is incremented each
  time Emacs is built.

Perhaps this is a better order:

  it starts at 1, is incremented each time Emacs is built, and is reset to 1 by
  @kbd{make bootstrap}.

Of course, as Glenn Morris points out, the way in which `it' is reset is not of
great importance. So, how about:

  it starts at 1, is incremented each time Emacs is built, and can be reset by
  something like @kbd{make clean} or @kbd{make bootstrap}.

bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice

[Stephen Berman]

On Thu, 5 Jul 2012 17:14:15 +0000 Michael Witten <mfwitten@gmail.com> wrote:

> On Thu, 05 Jul 2012 19:37:55 +0300, Eli Zaretskii <eliz@gnu.org> wrote:
>
>> it starts at 1, is reset to 1 by @kbd{make bootstrap}, and each build
>> of Emacs increments that number.
>
> In all clauses but the last, `it' (that is, the last number) is the subject.
> Moroever, the middle clause is already in the passive voice. So, for the sake of
> consistency, why not continue with both the subject `it' and that passive voice:
>
>   it starts at 1, is reset to 1 by @kbd{make bootstrap}, and is incremented each
>   time Emacs is built.
>
> Perhaps this is a better order:
>
>   it starts at 1, is incremented each time Emacs is built, and is reset to 1 by
>   @kbd{make bootstrap}.
>
> Of course, as Glenn Morris points out, the way in which `it' is reset is not of
> great importance. So, how about:
>
>   it starts at 1, is incremented each time Emacs is built, and can be reset by
>   something like @kbd{make clean} or @kbd{make bootstrap}.

Here's another attempt to satisfy the no passive preference:

    The last number in this string is not part of the Emacs release
    version number, but is a counter representing the build number; each
    time you rebuild Emacs, the last number increases by one (but
    building with @kbd{make clean} or @kbd{make bootstrap} resets it to
    1).

Steve Berman

bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for

[Richard Stallman]

    +  A @dfn{variable} is a name that can be bound to an object; binding
    +is frequently referred to as `setting', and the object to which
    +a variable is `set' is often called a `value' that the variable
    +`holds'.

This change might be ok, but please use @dfn around the terms that are
introduced, rather than single quotes.  @dfn exists precisely for
this.

--
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is

[Michael Witten]

On Thu, 05 Jul 2012 17:50:43 -0400, Richard Stallman wrote:

>     +  A @dfn{variable} is a name that can be bound to an object; binding
>     +is frequently referred to as `setting', and the object to which
>     +a variable is `set' is often called a `value' that the variable
>     +`holds'.
>
> This change might be ok, but please use @dfn around the terms that are
> introduced, rather than single quotes.  @dfn exists precisely for
> this.

The following is an updated patch; save this email and apply it with:

  git am -c "$path_to_saved_email"

--8<-----------8<-----------8<-----------8<-----------8<-----------8<---------

The terms `set' and `bind', `object' and `value', and `hold' are used
somewhat freely; this commit introduces more pedantic language (while
still mentioning the others).
---
 doc/lispref/intro.texi | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 5ca4d37..da4cd80 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -446,11 +446,14 @@ 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.
+  A @dfn{variable} is a name that can be bound to an object; binding
+is frequently referred to as @dfn{setting}, and the object to which
+a variable is set is often called a @dfn{value} that the variable
+@dfn{holds}.  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
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More preciselanguage for what a variable is

[Drew Adams]

> -  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.
> +  A @dfn{variable} is a name that can be bound to an object; binding
> +is frequently referred to as @dfn{setting}, and the object to which
> +a variable is set is often called a @dfn{value} that the variable
> +@dfn{holds}.  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.

FWIW, to me, a Lisp variable is not just a "name" that can be bound or set...
It is a Lisp symbol that is bound or set...

bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is

[Eli Zaretskii]

> Date: Thu, 05 Jul 2012 22:55:46 -0000
> From: Michael Witten <mfwitten@gmail.com>
> Cc: 11862@debbugs.gnu.org
> 
> +  A @dfn{variable} is a name that can be bound to an object; binding
> +is frequently referred to as @dfn{setting}, and the object to which
> +a variable is set is often called a @dfn{value} that the variable
> +@dfn{holds}.  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.

"Holds" is not a term, so it should be devoid of any markup (and not
in quotes, either).

bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is

[Michael Witten]

On Thu, 5 Jul 2012 18:58:12 -0700, Drew Adams wrote:

>> -  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.
>> +  A @dfn{variable} is a name that can be bound to an object; binding
>> +is frequently referred to as @dfn{setting}, and the object to which
>> +a variable is set is often called a @dfn{value} that the variable
>> +@dfn{holds}.  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.
>
> FWIW, to me, a Lisp variable is not just a "name" that can be bound
> or set... It is a Lisp symbol that is bound or set...

The following is an updated patch; save this email and apply it with:

  git am -c "$path_to_saved_email"

--8<-----------8<-----------8<-----------8<-----------8<-----------8<---------

The terms `set' and `bind', `object' and `value', and `hold' are used
somewhat freely; this commit introduces these terms with language that
is more pedantic, and it reorganizes the text, so that they are
introduced in [more] proper places, thereby reducing redundancy.

In particular:

  * The term `value' is introduced in node `Some Terms'; that term
    is used pervasively, so it should be brought to the reader's
    attention early on.

  * Node `A sample Variable Description' is reduced and reorganized.

      - The description of `variable' is removed entirely; such a
        descriptin is better placed in the node `Variables'. Moreover,
        this change is consistent with the text of the sibling node,
        `A Sample Function Description', which does not give such a
        description for a function, instead leaving that complex
        topic to more appropriate nodes, such as `Functions'.

      - The term `user options' is moved to the bottom of this node.

  * The node `Variables' is updated with more pedantic language.

      - The new introductory text makes a bolder association between
        variables and symbols (making the statement that a variable
        *is* a symbol, rather than the weaker statement that a variable
        is merely represented by a symbol); this may be worth more
        consideration.  
        
      - The term `@dfn{bound}' is introduced. There is another
        `@dfn{bound}' in `doc/lispref/functions.texi', though it
        may be simply viewed as a different, but related concept.

      - The terms `@dfn{setting}' and `@dfn{holds}' are introduced
        for the sake of pointing them out as common (if not official)
        lingo.
---
 doc/lispref/intro.texi     | 26 ++++++++++++--------------
 doc/lispref/variables.texi | 19 ++++++++++---------
 2 files changed, 22 insertions(+), 23 deletions(-)

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/variables.texi b/doc/lispref/variables.texi
index affaff4..863fd07 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -6,15 +6,16 @@
 @chapter Variables
 @cindex variable
 
-  A @dfn{variable} is a name used in a program to stand for a value.
-In Lisp, each variable is represented by a Lisp symbol
-(@pxref{Symbols}).  The variable name is simply the symbol's name, and
-the variable's value is stored in the symbol's value cell@footnote{To
-be precise, under the default @dfn{dynamic binding} rules the value
-cell always holds the variable's current value, but this is not the
-case under @dfn{lexical binding} rules.  @xref{Variable Scoping}, for
-details.}.  @xref{Symbol Components}.  In Emacs Lisp, the use of a
-symbol as a variable is independent of its use as a function name.
+  A @dfn{variable} is a symbol that is @dfn{bound} to an object
+(@pxref{Symbols}); binding is frequently referred to as @dfn{setting},
+and the object to which a variable is set is often called a value
+that the variable @dfn{holds}, in that the value is stored in the
+symbol's value cell@footnote{To be precise, under the default
+@dfn{dynamic binding} rules the value cell always holds the variable's
+current value, but this is not the case under @dfn{lexical binding}
+rules.  @xref{Variable Scoping}, for details.}.  @xref{Symbol Components}.
+In Emacs Lisp, the use of a symbol as a variable is independent of its
+use as a function name (@pxref{Function Names}).
 
   As previously noted in this manual, a Lisp program is represented
 primarily by Lisp objects, and only secondarily as text.  The textual
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is

[Wolfgang Jenkner]

On Fri, Jul 06 2012, Michael Witten wrote:

> +(@pxref{Symbols}); binding is frequently referred to as @dfn{setting},

This is a bit misleading, except when speaking of previously unbound
symbols or when using "is set" as a stative perfect.  Could you please
give an example where binding a bound symbol is described as "setting"
it?  IMHO, this would be a documentation bug.

Wolfgang

bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is

[Drew Adams]

> > 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#SECTION001150000000000
000000

And there is this, from the book "Successful Lisp":
http://psg.com/~dlamkins/sl/chapter03-06.html

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.
 

bug#11862: [PATCH 8a/9] doc/lispref/intro.texi: Introduce the term `value' early on

[Michael Witten]

The term `value' is used pervasively, so it should be brought to
the reader's attention early on; it is introduced in node `Some Terms'.

Originally, `doc/lispref/functions.texi' introduced both `@dfn{value}'
and `@dfn{return value}' in describing the result of a computation,
but now only `return value' is marked with `@dfn'.
---
 doc/lispref/functions.texi | 2 +-
 doc/lispref/intro.texi     | 9 +++++----
 2 files changed, 6 insertions(+), 5 deletions(-)

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.
 
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 5ca4d37..0766a23 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)}.
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 8b/2] doc/lispref/intro.texi: Reduce and reorganize node `A sample Variable Description'

[Michael Witten]

The description of `variable' is removed; such a descriptin is better
placed in the node `Variables'.

Moreover, this change is consistent with the text of the sibling node,
`A Sample Function Description', which does not give such a description
for a function, instead leaving that complex topic to more appropriate
nodes (such as node `Functions').

The term `user options' is moved to the bottom of the node.
---
 doc/lispref/intro.texi | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 0766a23..b62bceb 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -447,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
@@ -462,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
-- 
1.7.11.1.29.gf71be5c

bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is

[Richard Stallman]

In Lisp, binding a variable and setting a variable are different
operations.  This binds the variable foo:

  (let (foo) ...)

This sets the variable foo:

  (setq foo ...)

If anything in our Lisp manuals makes this difference blurry,
it ought to be fixed.

--
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#11862: [Copyright assignment]

[Chong Yidong]

If you intend to continue making corrections to the Lisp manual, we will
need a copyright assignment for your contributions.  Would you be
willing to sign one?

If so, please email the following information to fsf-records@gnu.org,
and they will send you the assignment form for your past and future
changes.  Please use your full name as the subject line of the message.

[What is your full legal name?]

[What is the name of the program or package you're contributing to?]


[Did you copy any files or text written by someone else in these changes?
Even if that material is free software, we need to know about it.]


[Do you have an employer who might have a basis to claim to own
your changes?  Do you attend a school which might make such a claim?]


[For the copyright registration, what country are you a citizen of?]


[What year were you born?]


[Please write your email address here.]


[Please write your snail address here.]



[Which files have you changed so far, and which new files have you written
so far?]