unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting
@ 2012-07-04 20:15 Michael Witten
  2012-07-04 20:15 ` bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma Michael Witten
                   ` (9 more replies)
  0 siblings, 10 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

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






^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
@ 2012-07-04 20:15 ` Michael Witten
  2012-07-05 10:13   ` Richard Stallman
  2012-07-04 20:15 ` bug#11862: [PATCH 2/9] doc/lispref/intro.texi: `can' -> `may' Michael Witten
                   ` (8 subsequent siblings)
  9 siblings, 1 reply; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

---
 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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 2/9] doc/lispref/intro.texi: `can' -> `may'
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
  2012-07-04 20:15 ` bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma Michael Witten
@ 2012-07-04 20:15 ` Michael Witten
  2012-07-05 10:13   ` Richard Stallman
  2012-07-04 20:15 ` bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense Michael Witten
                   ` (7 subsequent siblings)
  9 siblings, 1 reply; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

---
 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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
  2012-07-04 20:15 ` bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma Michael Witten
  2012-07-04 20:15 ` bug#11862: [PATCH 2/9] doc/lispref/intro.texi: `can' -> `may' Michael Witten
@ 2012-07-04 20:15 ` Michael Witten
  2012-07-05 10:13   ` Richard Stallman
  2012-07-04 20:15 ` bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language Michael Witten
                   ` (6 subsequent siblings)
  9 siblings, 1 reply; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
                   ` (2 preceding siblings ...)
  2012-07-04 20:15 ` bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense Michael Witten
@ 2012-07-04 20:15 ` Michael Witten
  2012-07-05 10:13   ` Richard Stallman
  2012-07-04 20:15 ` bug#11862: [PATCH 5/9] doc/lispref/intro.texi: Use singular form in a sentence Michael Witten
                   ` (5 subsequent siblings)
  9 siblings, 1 reply; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 5/9] doc/lispref/intro.texi: Use singular form in a sentence
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
                   ` (3 preceding siblings ...)
  2012-07-04 20:15 ` bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language Michael Witten
@ 2012-07-04 20:15 ` Michael Witten
  2012-07-04 20:15 ` bug#11862: [PATCH 6/9] doc/lispref/intro.texi: Re-fill a paragraph Michael Witten
                   ` (4 subsequent siblings)
  9 siblings, 0 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 6/9] doc/lispref/intro.texi: Re-fill a paragraph
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
                   ` (4 preceding siblings ...)
  2012-07-04 20:15 ` bug#11862: [PATCH 5/9] doc/lispref/intro.texi: Use singular form in a sentence Michael Witten
@ 2012-07-04 20:15 ` Michael Witten
  2012-07-04 20:15 ` bug#11862: [PATCH 7/9] doc/lispref/intro.texi: `optional' -> `&optional'; Michael Witten
                   ` (3 subsequent siblings)
  9 siblings, 0 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 7/9] doc/lispref/intro.texi: `optional' -> `&optional';
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
                   ` (5 preceding siblings ...)
  2012-07-04 20:15 ` bug#11862: [PATCH 6/9] doc/lispref/intro.texi: Re-fill a paragraph Michael Witten
@ 2012-07-04 20:15 ` Michael Witten
  2012-07-05  3:03   ` Glenn Morris
  2012-07-04 20:15 ` bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for Michael Witten
                   ` (2 subsequent siblings)
  9 siblings, 1 reply; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
                   ` (6 preceding siblings ...)
  2012-07-04 20:15 ` bug#11862: [PATCH 7/9] doc/lispref/intro.texi: `optional' -> `&optional'; Michael Witten
@ 2012-07-04 20:15 ` Michael Witten
  2012-07-05 21:50   ` Richard Stallman
  2012-07-04 20:16 ` bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice Michael Witten
  2012-07-05  2:52 ` bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Stefan Monnier
  9 siblings, 1 reply; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:15 UTC (permalink / raw)
  To: 11862

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
                   ` (7 preceding siblings ...)
  2012-07-04 20:15 ` bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for Michael Witten
@ 2012-07-04 20:16 ` Michael Witten
  2012-07-05 10:14   ` Richard Stallman
  2012-07-05  2:52 ` bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Stefan Monnier
  9 siblings, 1 reply; 36+ messages in thread
From: Michael Witten @ 2012-07-04 20:16 UTC (permalink / raw)
  To: 11862

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting
  2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
                   ` (8 preceding siblings ...)
  2012-07-04 20:16 ` bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice Michael Witten
@ 2012-07-05  2:52 ` Stefan Monnier
       [not found]   ` <CAMOZ1BsRkioUhGGOuFrmbkMRnJiQ6h=tviNODS11BjG3_jYVbA@mail.gmail.com>
  9 siblings, 1 reply; 36+ messages in thread
From: Stefan Monnier @ 2012-07-05  2:52 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862-done

> 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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 7/9] doc/lispref/intro.texi: `optional' -> `&optional';
  2012-07-04 20:15 ` bug#11862: [PATCH 7/9] doc/lispref/intro.texi: `optional' -> `&optional'; Michael Witten
@ 2012-07-05  3:03   ` Glenn Morris
  0 siblings, 0 replies; 36+ messages in thread
From: Glenn Morris @ 2012-07-05  3:03 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862

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}.





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting
       [not found]   ` <CAMOZ1BsRkioUhGGOuFrmbkMRnJiQ6h=tviNODS11BjG3_jYVbA@mail.gmail.com>
@ 2012-07-05  7:09     ` Glenn Morris
  0 siblings, 0 replies; 36+ messages in thread
From: Glenn Morris @ 2012-07-05  7:09 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862


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






^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma
  2012-07-04 20:15 ` bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma Michael Witten
@ 2012-07-05 10:13   ` Richard Stallman
  2012-07-05 16:52     ` bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier Michael Witten
  0 siblings, 1 reply; 36+ messages in thread
From: Richard Stallman @ 2012-07-05 10:13 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862

    -  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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 2/9] doc/lispref/intro.texi: `can' -> `may'
  2012-07-04 20:15 ` bug#11862: [PATCH 2/9] doc/lispref/intro.texi: `can' -> `may' Michael Witten
@ 2012-07-05 10:13   ` Richard Stallman
  0 siblings, 0 replies; 36+ messages in thread
From: Richard Stallman @ 2012-07-05 10:13 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862

       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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense
  2012-07-04 20:15 ` bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense Michael Witten
@ 2012-07-05 10:13   ` Richard Stallman
  0 siblings, 0 replies; 36+ messages in thread
From: Richard Stallman @ 2012-07-05 10:13 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862

    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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language
  2012-07-04 20:15 ` bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language Michael Witten
@ 2012-07-05 10:13   ` Richard Stallman
  0 siblings, 0 replies; 36+ messages in thread
From: Richard Stallman @ 2012-07-05 10:13 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862

       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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice
  2012-07-04 20:16 ` bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice Michael Witten
@ 2012-07-05 10:14   ` Richard Stallman
  2012-07-05 14:04     ` Stephen Berman
  0 siblings, 1 reply; 36+ messages in thread
From: Richard Stallman @ 2012-07-05 10:14 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862

     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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice
  2012-07-05 10:14   ` Richard Stallman
@ 2012-07-05 14:04     ` Stephen Berman
  2012-07-05 16:37       ` Eli Zaretskii
  0 siblings, 1 reply; 36+ messages in thread
From: Stephen Berman @ 2012-07-05 14:04 UTC (permalink / raw)
  To: rms; +Cc: 11862

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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice
  2012-07-05 14:04     ` Stephen Berman
@ 2012-07-05 16:37       ` Eli Zaretskii
  2012-07-05 16:59         ` Glenn Morris
  2012-07-05 17:14         ` Michael Witten
  0 siblings, 2 replies; 36+ messages in thread
From: Eli Zaretskii @ 2012-07-05 16:37 UTC (permalink / raw)
  To: Stephen Berman; +Cc: 11862, rms

> 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.





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier
  2012-07-05 10:13   ` Richard Stallman
@ 2012-07-05 16:52     ` Michael Witten
  0 siblings, 0 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-05 16:52 UTC (permalink / raw)
  To: Richard Stallman; +Cc: 11862

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.





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice
  2012-07-05 16:37       ` Eli Zaretskii
@ 2012-07-05 16:59         ` Glenn Morris
  2012-07-05 17:14         ` Michael Witten
  1 sibling, 0 replies; 36+ messages in thread
From: Glenn Morris @ 2012-07-05 16:59 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 11862, Stephen Berman, rms


>> 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...).





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice
  2012-07-05 16:37       ` Eli Zaretskii
  2012-07-05 16:59         ` Glenn Morris
@ 2012-07-05 17:14         ` Michael Witten
  2012-07-05 19:09           ` Stephen Berman
  1 sibling, 1 reply; 36+ messages in thread
From: Michael Witten @ 2012-07-05 17:14 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Stephen Berman, Richard Stallman, 11862

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}.





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice
  2012-07-05 17:14         ` Michael Witten
@ 2012-07-05 19:09           ` Stephen Berman
  0 siblings, 0 replies; 36+ messages in thread
From: Stephen Berman @ 2012-07-05 19:09 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862, Richard Stallman

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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for
  2012-07-04 20:15 ` bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for Michael Witten
@ 2012-07-05 21:50   ` Richard Stallman
  2012-07-05 22:55     ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is Michael Witten
  0 siblings, 1 reply; 36+ messages in thread
From: Richard Stallman @ 2012-07-05 21:50 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862

    +  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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is
  2012-07-05 21:50   ` Richard Stallman
@ 2012-07-05 22:55     ` Michael Witten
  2012-07-06  1:58       ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More preciselanguage " Drew Adams
  2012-07-06  6:40       ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is Eli Zaretskii
  0 siblings, 2 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-05 22:55 UTC (permalink / raw)
  To: Richard Stallman; +Cc: 11862

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More preciselanguage for what a variable is
  2012-07-05 22:55     ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is Michael Witten
@ 2012-07-06  1:58       ` Drew Adams
  2012-07-06  8:07         ` bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language " Michael Witten
  2012-07-06  6:40       ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is Eli Zaretskii
  1 sibling, 1 reply; 36+ messages in thread
From: Drew Adams @ 2012-07-06  1:58 UTC (permalink / raw)
  To: 'Michael Witten', 'Richard Stallman'; +Cc: 11862

> -  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...






^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is
  2012-07-05 22:55     ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is Michael Witten
  2012-07-06  1:58       ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More preciselanguage " Drew Adams
@ 2012-07-06  6:40       ` Eli Zaretskii
  1 sibling, 0 replies; 36+ messages in thread
From: Eli Zaretskii @ 2012-07-06  6:40 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862, rms

> 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).





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is
  2012-07-06  1:58       ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More preciselanguage " Drew Adams
@ 2012-07-06  8:07         ` Michael Witten
  2012-07-06 15:55           ` Wolfgang Jenkner
  2012-07-08  4:41           ` bug#11862: [Copyright assignment] Chong Yidong
  0 siblings, 2 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-06  8:07 UTC (permalink / raw)
  To: Drew Adams; +Cc: 11862, Richard Stallman

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is
  2012-07-06  8:07         ` bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language " Michael Witten
@ 2012-07-06 15:55           ` Wolfgang Jenkner
  2012-07-06 16:45             ` Drew Adams
  2012-07-07  9:18             ` bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is Richard Stallman
  2012-07-08  4:41           ` bug#11862: [Copyright assignment] Chong Yidong
  1 sibling, 2 replies; 36+ messages in thread
From: Wolfgang Jenkner @ 2012-07-06 15:55 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862, Richard Stallman

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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is
  2012-07-06 15:55           ` Wolfgang Jenkner
@ 2012-07-06 16:45             ` Drew Adams
  2012-07-06 20:06               ` bug#11862: Splitting and simplifying [PATCH 8/9] Michael Witten
  2012-07-07  9:18             ` bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is Richard Stallman
  1 sibling, 1 reply; 36+ messages in thread
From: Drew Adams @ 2012-07-06 16:45 UTC (permalink / raw)
  To: 'Wolfgang Jenkner', 'Michael Witten'
  Cc: 11862, 'Richard Stallman'

> > 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






^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: Splitting and simplifying [PATCH 8/9]
  2012-07-06 16:45             ` Drew Adams
@ 2012-07-06 20:06               ` Michael Witten
  2012-07-06 20:17                 ` bug#11862: [PATCH 8a/9] doc/lispref/intro.texi: Introduce the term `value' early on Michael Witten
  2012-07-06 20:18                 ` bug#11862: [PATCH 8b/2] doc/lispref/intro.texi: Reduce and reorganize node `A sample Variable Description' Michael Witten
  0 siblings, 2 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-06 20:06 UTC (permalink / raw)
  To: Drew Adams; +Cc: 11862, Wolfgang Jenkner, Richard Stallman

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.
 





^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8a/9] doc/lispref/intro.texi: Introduce the term `value' early on
  2012-07-06 20:06               ` bug#11862: Splitting and simplifying [PATCH 8/9] Michael Witten
@ 2012-07-06 20:17                 ` Michael Witten
  2012-07-06 20:18                 ` bug#11862: [PATCH 8b/2] doc/lispref/intro.texi: Reduce and reorganize node `A sample Variable Description' Michael Witten
  1 sibling, 0 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-06 20:17 UTC (permalink / raw)
  To: Drew Adams; +Cc: 11862, Wolfgang Jenkner, Richard Stallman

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8b/2] doc/lispref/intro.texi: Reduce and reorganize node `A sample Variable Description'
  2012-07-06 20:06               ` bug#11862: Splitting and simplifying [PATCH 8/9] Michael Witten
  2012-07-06 20:17                 ` bug#11862: [PATCH 8a/9] doc/lispref/intro.texi: Introduce the term `value' early on Michael Witten
@ 2012-07-06 20:18                 ` Michael Witten
  1 sibling, 0 replies; 36+ messages in thread
From: Michael Witten @ 2012-07-06 20:18 UTC (permalink / raw)
  To: Drew Adams; +Cc: 11862, Wolfgang Jenkner, Richard Stallman

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






^ permalink raw reply related	[flat|nested] 36+ messages in thread

* bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is
  2012-07-06 15:55           ` Wolfgang Jenkner
  2012-07-06 16:45             ` Drew Adams
@ 2012-07-07  9:18             ` Richard Stallman
  1 sibling, 0 replies; 36+ messages in thread
From: Richard Stallman @ 2012-07-07  9:18 UTC (permalink / raw)
  To: Wolfgang Jenkner; +Cc: 11862

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





^ permalink raw reply	[flat|nested] 36+ messages in thread

* bug#11862: [Copyright assignment]
  2012-07-06  8:07         ` bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language " Michael Witten
  2012-07-06 15:55           ` Wolfgang Jenkner
@ 2012-07-08  4:41           ` Chong Yidong
  1 sibling, 0 replies; 36+ messages in thread
From: Chong Yidong @ 2012-07-08  4:41 UTC (permalink / raw)
  To: Michael Witten; +Cc: 11862

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?]





^ permalink raw reply	[flat|nested] 36+ messages in thread

end of thread, other threads:[~2012-07-08  4:41 UTC | newest]

Thread overview: 36+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-07-04 20:15 bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Michael Witten
2012-07-04 20:15 ` bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier with a comma Michael Witten
2012-07-05 10:13   ` Richard Stallman
2012-07-05 16:52     ` bug#11862: [PATCH 1/9] doc/lispref/intro.texi: Offset modifier Michael Witten
2012-07-04 20:15 ` bug#11862: [PATCH 2/9] doc/lispref/intro.texi: `can' -> `may' Michael Witten
2012-07-05 10:13   ` Richard Stallman
2012-07-04 20:15 ` bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense Michael Witten
2012-07-05 10:13   ` Richard Stallman
2012-07-04 20:15 ` bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language Michael Witten
2012-07-05 10:13   ` Richard Stallman
2012-07-04 20:15 ` bug#11862: [PATCH 5/9] doc/lispref/intro.texi: Use singular form in a sentence Michael Witten
2012-07-04 20:15 ` bug#11862: [PATCH 6/9] doc/lispref/intro.texi: Re-fill a paragraph Michael Witten
2012-07-04 20:15 ` bug#11862: [PATCH 7/9] doc/lispref/intro.texi: `optional' -> `&optional'; Michael Witten
2012-07-05  3:03   ` Glenn Morris
2012-07-04 20:15 ` bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for Michael Witten
2012-07-05 21:50   ` Richard Stallman
2012-07-05 22:55     ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is Michael Witten
2012-07-06  1:58       ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More preciselanguage " Drew Adams
2012-07-06  8:07         ` bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language " Michael Witten
2012-07-06 15:55           ` Wolfgang Jenkner
2012-07-06 16:45             ` Drew Adams
2012-07-06 20:06               ` bug#11862: Splitting and simplifying [PATCH 8/9] Michael Witten
2012-07-06 20:17                 ` bug#11862: [PATCH 8a/9] doc/lispref/intro.texi: Introduce the term `value' early on Michael Witten
2012-07-06 20:18                 ` bug#11862: [PATCH 8b/2] doc/lispref/intro.texi: Reduce and reorganize node `A sample Variable Description' Michael Witten
2012-07-07  9:18             ` bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is Richard Stallman
2012-07-08  4:41           ` bug#11862: [Copyright assignment] Chong Yidong
2012-07-06  6:40       ` bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is Eli Zaretskii
2012-07-04 20:16 ` bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice Michael Witten
2012-07-05 10:14   ` Richard Stallman
2012-07-05 14:04     ` Stephen Berman
2012-07-05 16:37       ` Eli Zaretskii
2012-07-05 16:59         ` Glenn Morris
2012-07-05 17:14         ` Michael Witten
2012-07-05 19:09           ` Stephen Berman
2012-07-05  2:52 ` bug#11862: [PATCH 0/9] doc/lispref/intro.texi: Copyediting Stefan Monnier
     [not found]   ` <CAMOZ1BsRkioUhGGOuFrmbkMRnJiQ6h=tviNODS11BjG3_jYVbA@mail.gmail.com>
2012-07-05  7:09     ` Glenn Morris

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).