[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language
From: |
Michael Witten |
Subject: |
bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is |
Date: |
Fri, 06 Jul 2012 08:07:31 -0000 |
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 7/9] doc/lispref/intro.texi: `optional' -> `&optional';, (continued)
- bug#11862: [PATCH 5/9] doc/lispref/intro.texi: Use singular form in a sentence, Michael Witten, 2012/07/04
- bug#11862: [PATCH 4/9] doc/lispref/intro.texi: More precise language, Michael Witten, 2012/07/04
- bug#11862: [PATCH 3/9] doc/lispref/intro.texi: Eradicate that pesky future tense, Michael Witten, 2012/07/04
- bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for, Michael Witten, 2012/07/04
- bug#11862: [PATCH 8/9] doc/lispref/intro.texi: More precise language for, Richard Stallman, 2012/07/05
- bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is, Michael Witten, 2012/07/05
- bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More preciselanguage for what a variable is, Drew Adams, 2012/07/05
- bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is,
Michael Witten <=
- bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is, Wolfgang Jenkner, 2012/07/06
- bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is, Drew Adams, 2012/07/06
- bug#11862: Splitting and simplifying [PATCH 8/9], Michael Witten, 2012/07/06
- bug#11862: [PATCH 8a/9] doc/lispref/intro.texi: Introduce the term `value' early on, Michael Witten, 2012/07/06
- bug#11862: [PATCH 8b/2] doc/lispref/intro.texi: Reduce and reorganize node `A sample Variable Description', Michael Witten, 2012/07/06
- bug#11862: [PATCH 8/9 v3] doc/lispref/intro.texi: More precise language for what a variable is, Richard Stallman, 2012/07/07
- bug#11862: [Copyright assignment], Chong Yidong, 2012/07/08
- bug#11862: [PATCH 8/9 v2] doc/lispref/intro.texi: More precise language for what a variable is, Eli Zaretskii, 2012/07/06
bug#11862: [PATCH 6/9] doc/lispref/intro.texi: Re-fill a paragraph, Michael Witten, 2012/07/04
bug#11862: [PATCH 9/9] doc/lispref/intro.texi: Use passive voice, Michael Witten, 2012/07/04