From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Michael Witten Newsgroups: gmane.emacs.bugs 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 Message-ID: <0c2cb6909a904ffeb3010bf4ca2e40b2-mfwitten@gmail.com> References: <22f1c29cd7e44a3e91ca67e534dc03a4-mfwitten@gmail.com> <3c1c3c1cfe3840e19551bfd0424eb99d-mfwitten@gmail.com> NNTP-Posting-Host: plane.gmane.org X-Trace: dough.gmane.org 1341562156 25764 80.91.229.3 (6 Jul 2012 08:09:16 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 6 Jul 2012 08:09:16 +0000 (UTC) Cc: 11862@debbugs.gnu.org, Richard Stallman To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 06 10:09:13 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Sn3bE-0007AB-6J for geb-bug-gnu-emacs@m.gmane.org; Fri, 06 Jul 2012 10:09:12 +0200 Original-Received: from localhost ([::1]:44459 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Sn3bC-0002xA-Vq for geb-bug-gnu-emacs@m.gmane.org; Fri, 06 Jul 2012 04:09:10 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:34182) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Sn3bA-0002wY-1t for bug-gnu-emacs@gnu.org; Fri, 06 Jul 2012 04:09:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Sn3b7-00033C-Q2 for bug-gnu-emacs@gnu.org; Fri, 06 Jul 2012 04:09:07 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:41844) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Sn3b7-000337-Jy for bug-gnu-emacs@gnu.org; Fri, 06 Jul 2012 04:09:05 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1Sn3ft-0004gg-UB for bug-gnu-emacs@gnu.org; Fri, 06 Jul 2012 04:14:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Michael Witten Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 06 Jul 2012 08:14:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 11862 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 11862-submit@debbugs.gnu.org id=B11862.134156240617970 (code B ref 11862); Fri, 06 Jul 2012 08:14:01 +0000 Original-Received: (at 11862) by debbugs.gnu.org; 6 Jul 2012 08:13:26 +0000 Original-Received: from localhost ([127.0.0.1]:51390 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1Sn3fK-0004fm-3z for submit@debbugs.gnu.org; Fri, 06 Jul 2012 04:13:26 -0400 Original-Received: from mail-wg0-f46.google.com ([74.125.82.46]:53786) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1Sn3fG-0004fe-F4 for 11862@debbugs.gnu.org; Fri, 06 Jul 2012 04:13:24 -0400 Original-Received: by wgbdq10 with SMTP id dq10so8629515wgb.15 for <11862@debbugs.gnu.org>; Fri, 06 Jul 2012 01:08:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=subject:date:from:to:cc:message-id:in-reply-to:references; bh=QHqWgRyUl9rh9BcTYcJbX466Azci9Nv+LxJINOGsHwk=; b=VXqWqKZN8RZIimpQLvuSh4ZcoFfGSbD1Syrk+6vccotztK1ynNQasnRNZZqV9n+HLt o73DyZBxKgu4eSB33UIOvAhKEKUiqhQNf/0t+ITme5oJ3CCUbkI/rWZccYTsHmXoSM34 9W+lCDiLMScCeqZD/wsqNf5Kpd5isskwV1EdXtGQ5Sd7VfX2vIW+w6SqRiwGVLjaBZgQ Ptq6/J0+eZGZHDUnhLYXNneeRB9YrBLOw5HpQhUCBSY7l/ZuGNDoQFlG9FafnQNk6GK/ EB6tiGTbTlUHOYrSziw4yU/2qZGNBpTTAoKLYAgDlksAt6AUIUSHHJk6vX748eUjlAmR pccQ== Original-Received: by 10.180.20.239 with SMTP id q15mr5633019wie.13.1341562104473; Fri, 06 Jul 2012 01:08:24 -0700 (PDT) Original-Received: from gmail.com ([95.211.153.115]) by mx.google.com with ESMTPS id h9sm4500036wiz.1.2012.07.06.01.08.21 (version=TLSv1/SSLv3 cipher=OTHER); Fri, 06 Jul 2012 01:08:23 -0700 (PDT) In-Reply-To: X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:61641 Archived-At: 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