[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] feature/gnus-select 590166c 151/218: Firm up documentation
From: |
Andrew G Cohen |
Subject: |
[Emacs-diffs] feature/gnus-select 590166c 151/218: Firm up documentation of generalized variables |
Date: |
Fri, 14 Dec 2018 03:35:20 -0500 (EST) |
branch: feature/gnus-select
commit 590166c829f43981f94f86714228b3e5de171d87
Author: Alan Mackenzie <address@hidden>
Commit: Andrew G Cohen <address@hidden>
Firm up documentation of generalized variables
* doc/lispref/variables.texi (Generalized Variables)
(Setting Generalized Variables): Define a generalized variable as something
setf can write to. Remove the insinuation that hackers have poor memories.
State explicitly that the list of GVs given is complete. Remove the
suggestion that `setf' has superseded, or is in the process of superseding,
`setq'. Make minor corrections to the English.
---
doc/lispref/variables.texi | 34 ++++++++++++++++++----------------
1 file changed, 18 insertions(+), 16 deletions(-)
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index aecee6f..b80bc88 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -2317,11 +2317,12 @@ Attempting to assign them any other value will result
in an error:
@cindex generalized variable
@cindex place form
-A @dfn{generalized variable} or @dfn{place form} is one of the many places
-in Lisp memory where values can be stored. The simplest place form is
-a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements
-of arrays, properties of symbols, and many other locations are also
-places where Lisp values are stored.
+A @dfn{generalized variable} or @dfn{place form} is one of the many
+places in Lisp memory where values can be stored using the @code{setf}
+macro (@pxref{Setting Generalized Variables}). The simplest place
+form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of
+lists, elements of arrays, properties of symbols, and many other
+locations are also places where Lisp values get stored.
Generalized variables are analogous to lvalues in the C
language, where @samp{x = a[i]} gets an element from an array
@@ -2342,8 +2343,8 @@ variables. The @code{setf} form is like @code{setq},
except that it
accepts arbitrary place forms on the left side rather than just
symbols. For example, @code{(setf (car a) b)} sets the car of
@code{a} to @code{b}, doing the same operation as @code{(setcar a b)},
-but without having to remember two separate functions for setting and
-accessing every type of place.
+but without you having to use two separate functions for setting and
+accessing this type of place.
@defmac setf [place address@hidden
This macro evaluates @var{form} and stores it in @var{place}, which
@@ -2353,18 +2354,19 @@ just as with @code{setq}. @code{setf} returns the
value of the last
@var{form}.
@end defmac
-The following Lisp forms will work as generalized variables, and
-so may appear in the @var{place} argument of @code{setf}:
+The following Lisp forms are the forms in Emacs that will work as
+generalized variables, and so may appear in the @var{place} argument
+of @code{setf}:
@itemize
@item
-A symbol naming a variable. In other words, @code{(setf x y)} is
-exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
-strictly speaking redundant given that @code{setf} exists. Many
-programmers continue to prefer @code{setq} for setting simple
-variables, though, purely for stylistic or historical reasons.
-The macro @code{(setf x y)} actually expands to @code{(setq x y)},
-so there is no performance penalty for using it in compiled code.
+A symbol. In other words, @code{(setf x y)} is exactly equivalent to
address@hidden(setq x y)}, and @code{setq} itself is strictly speaking
+redundant given that @code{setf} exists. Most programmers will
+continue to prefer @code{setq} for setting simple variables, though,
+for stylistic and historical reasons. The macro @code{(setf x y)}
+actually expands to @code{(setq x y)}, so there is no performance
+penalty for using it in compiled code.
@item
A call to any of the following standard Lisp functions:
- [Emacs-diffs] feature/gnus-select aa527be 071/218: Replace an obsolete alias in tpu-mapper, (continued)
- [Emacs-diffs] feature/gnus-select aa527be 071/218: Replace an obsolete alias in tpu-mapper, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 16cfb9a 074/218: * lisp/progmodes/ada-mode.el (ada-clean-buffer-before-saving): Doc fix., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 29b7170 073/218: Doc fixes re obsolete items, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 77bf8e0 077/218: Fix line-wrapping for term.el (Bug#30775), Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select e274f0b 075/218: Fix some allout.el aliases, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select c6e52fa 088/218: Improve robustness in tramp-sh.el, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select c4bd17e 079/218: ; * test/README: Fix typo, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 4a6cf41 156/218: * doc/lispref/internals.texi (Writing Emacs Primitives): Fix grammar., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select b4377a3 164/218: Handle possible classtype values in eieio-persistent-read, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select ff16207 153/218: ; * autogen.sh: Comment., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 590166c 151/218: Firm up documentation of generalized variables,
Andrew G Cohen <=
- [Emacs-diffs] feature/gnus-select a3e7de9 086/218: Fix mouse-set-point when line numbers are displayed, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 57200d8 084/218: Replace "carriage-return" by "carriage return" in manuals, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 620b63a 092/218: * lisp/progmodes/verilog-mode.el (verilog-mode): Quieten compilation., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 3ef9943 067/218: * lisp/obsolete/options.el: Remove file., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 2544299 076/218: Try to stop tramp test hangs on hydra, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 520498d 091/218: Improve port to NetBSD tzalloc, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 02b297b 044/218: ; Revert "; Tracing for eieio-test random failure (Bug#24503)", Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select a381e7e 002/218: Define if-let* and derivatives as aliases for if-let etc, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select a8e5163 070/218: Minor changes in mule.texi, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 03e7331 089/218: * lisp/pcomplete.el (pcomplete-here): Move before first reference., Andrew G Cohen, 2018/12/14