all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#67734: 30.0.50; Don't mention `set` in the ELisp intro
@ 2023-12-09 23:17 Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2023-12-14 22:30 ` Stefan Kangas
  0 siblings, 1 reply; 4+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-12-09 23:17 UTC (permalink / raw)
  To: 67734

[-- Attachment #1: Type: text/plain, Size: 615 bytes --]

Package: Emacs
Version: 30.0.50


The ELisp intro needs to be updated to the world of static scoping.
I haven't really looked at doing that, but the patch below can be
considered as a step in that direction.
In any case, I think it's a good change on its own.

It removes all mentions of the `set` function.
`set` cannot be used on statically scoped variables and I can't see what
it brings to the reader of the ELisp intro (except maybe for explaining
the "q" in `setq`) to first tell them about `set` only to turn around
and tell them they'll never use it.

Suggestions for improvements welcome,


        Stefan

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: elisp-intro.patch --]
[-- Type: text/x-diff, Size: 6098 bytes --]

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index eb8ff413b79..4246742a17e 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -2280,34 +2280,33 @@ set & setq
 
 @cindex @samp{bind} defined
 There are several ways by which a variable can be given a value.  One of
-the ways is to use either the function @code{set} or the special form
+the ways is to use the special form
 @code{setq}.  Another way is to use @code{let} (@pxref{let}).  (The
 jargon for this process is to @dfn{bind} a variable to a value.)
 
-The following sections not only describe how @code{set} and @code{setq}
-work but also illustrate how arguments are passed.
+The following sections not only describe how @code{setq}
+works but also illustrate how arguments are passed.
 
 @menu
-* Using set::                  Setting values.
-* Using setq::                 Setting a quoted value.
+* Using setq::                 Setting variables.
 * Counting::                   Using @code{setq} to count.
 @end menu
 
-@node Using set
-@subsection Using @code{set}
+@node Using setq
+@subsection Using @code{setq}
 @findex set
 
-To set the value of the symbol @code{flowers} to the list @code{'(rose
+To set the value of the symbol @code{flowers} to the list @code{(rose
 violet daisy buttercup)}, evaluate the following expression by
 positioning the cursor after the expression and typing @kbd{C-x C-e}.
 
 @smallexample
-(set 'flowers '(rose violet daisy buttercup))
+(setq flowers '(rose violet daisy buttercup))
 @end smallexample
 
 @noindent
 The list @code{(rose violet daisy buttercup)} will appear in the echo
-area.  This is what is @emph{returned} by the @code{set} function.  As a
+area.  This is what is @emph{returned} by the @code{setq} special form.  As a
 side effect, the symbol @code{flowers} is bound to the list; that is,
 the symbol @code{flowers}, which can be viewed as a variable, is given
 the list as its value.  (This process, by the way, illustrates how a
@@ -2316,7 +2315,7 @@ Using set
 Lisp function must return a value if it does not get an error, but it
 will only have a side effect if it is designed to have one.)
 
-After evaluating the @code{set} expression, you can evaluate the symbol
+After evaluating the @code{setq} expression, you can evaluate the symbol
 @code{flowers} and it will return the value you just set.  Here is the
 symbol.  Place your cursor after it and type @kbd{C-x C-e}.
 
@@ -2336,29 +2335,7 @@ Using set
 'flowers
 @end smallexample
 
-Note also, that when you use @code{set}, you need to quote both
-arguments to @code{set}, unless you want them evaluated.  Since we do
-not want either argument evaluated, neither the variable
-@code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
-are quoted.  (When you use @code{set} without quoting its first
-argument, the first argument is evaluated before anything else is
-done.  If you did this and @code{flowers} did not have a value
-already, you would get an error message that the @samp{Symbol's value
-as variable is void}; on the other hand, if @code{flowers} did return
-a value after it was evaluated, the @code{set} would attempt to set
-the value that was returned.  There are situations where this is the
-right thing for the function to do; but such situations are rare.)
-
-@node Using setq
-@subsection Using @code{setq}
-@findex setq
-
-As a practical matter, you almost always quote the first argument to
-@code{set}.  The combination of @code{set} and a quoted first argument
-is so common that it has its own name: the special form @code{setq}.
-This special form is just like @code{set} except that the first argument
-is quoted automatically, so you don't need to type the quote mark
-yourself.  Also, as an added convenience, @code{setq} permits you to set
+Also, as an added convenience, @code{setq} permits you to set
 several different variables to different values, all in one expression.
 
 To set the value of the variable @code{carnivores} to the list
@@ -2369,18 +2346,6 @@ Using setq
 (setq carnivores '(lion tiger leopard))
 @end smallexample
 
-@noindent
-This is exactly the same as using @code{set} except the first argument
-is automatically quoted by @code{setq}.  (The @samp{q} in @code{setq}
-means @code{quote}.)
-
-@need 1250
-With @code{set}, the expression would look like this:
-
-@smallexample
-(set 'carnivores '(lion tiger leopard))
-@end smallexample
-
 Also, @code{setq} can be used to assign different values to
 different variables.  The first argument is bound to the value
 of the second argument, the third argument is bound to the value of the
@@ -2401,8 +2366,8 @@ Using setq
 formatted lists.)
 
 Although I have been using the term ``assign'', there is another way of
-thinking about the workings of @code{set} and @code{setq}; and that is to
-say that @code{set} and @code{setq} make the symbol @emph{point} to the
+thinking about the workings of @code{setq}; and that is to
+say that @code{setq} makes the symbol @emph{point} to the
 list.  This latter way of thinking is very common and in forthcoming
 chapters we shall come upon at least one symbol that has ``pointer'' as
 part of its name.  The name is chosen because the symbol has a value,
@@ -3598,6 +3563,8 @@ Prevent confusion
 @unnumberedsubsec @code{let} Prevents Confusion
 @end ifnottex
 
+@c FIXME!! lexbind!!
+
 @cindex @samp{local variable} defined
 @cindex @samp{variable, local}, defined
 The @code{let} special form prevents confusion.  @code{let} creates a
@@ -4471,9 +4438,7 @@ Review
 The @code{setq} special form sets the value of its first argument to the
 value of the second argument.  The first argument is automatically
 quoted by @code{setq}.  It does the same for succeeding pairs of
-arguments.  Another function, @code{set}, takes only two arguments and
-evaluates both of them before setting the value returned by its first
-argument to the value returned by its second argument.
+arguments.
 
 @item buffer-name
 Without an argument, return the name of the buffer, as a string.

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

end of thread, other threads:[~2023-12-21 15:25 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-12-09 23:17 bug#67734: 30.0.50; Don't mention `set` in the ELisp intro Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-12-14 22:30 ` Stefan Kangas
2023-12-16 18:06   ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-12-21 15:25     ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors

Code repositories for project(s) associated with this external index

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

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.