-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*- mode: texinfo; coding: utf-8 -*-
@comment %**start of header
@setfilename ../../info/eintr.info
@c setfilename emacs-lisp-intro.info
Distributed with Emacs version @value{EMACSVER}.
@end ifnottex
@sp 1
-Copyright @copyright{} 1990--1995, 1997, 2001--2015 Free Software
+Copyright @copyright{} 1990--1995, 1997, 2001--2016 Free Software
Foundation, Inc.
@sp 1
Although these are examples, the programs are real. I use them.
Other people use them. You may use them. Beyond the fragments of
programs used for illustrations, there is very little in here that is
-``just for teaching purposes''; what you see is used. This is a great
+just for teaching purposes; what you see is used. This is a great
advantage of Emacs Lisp: it is easy to learn to use it for work.
@end ignore
information is formally introduced.)
When you read this text, you are not expected to learn everything the
-first time. Frequently, you need only make, as it were, a ``nodding
-acquaintance'' with some of the items mentioned. My hope is that I have
+first time. Frequently, you need make only a nodding
+acquaintance with some of the items mentioned. My hope is that I have
structured the text and given you enough hints that you will be alert to
what is important, and concentrate on it.
-You will need to ``dive into'' some paragraphs; there is no other way
+You will need to dive into some paragraphs; there is no other way
to read them. But I have tried to keep down the number of such
paragraphs. This book is intended as an approachable hill, rather than
as a daunting mountain.
press the @key{\} key.
In addition to typing a lone keychord, you can prefix what you type
-with @kbd{C-u}, which is called the ``universal argument''. The
+with @kbd{C-u}, which is called the @dfn{universal argument}. The
@kbd{C-u} keychord passes an argument to the subsequent command.
Thus, to indent a region of plain text by 6 spaces, mark the region,
and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number,
claim is unwarranted. Lisp stands for LISt Processing, and the
programming language handles @emph{lists} (and lists of lists) by
putting them between parentheses. The parentheses mark the boundaries
-of the list. Sometimes a list is preceded by a single apostrophe or
-quotation mark, @samp{'}@footnote{The single apostrophe or quotation
-mark is an abbreviation for the function @code{quote}; you need not
-think about functions now; functions are defined in @ref{Making
-Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
+of the list. Sometimes a list is preceded by an apostrophe @samp{'},
+called a @dfn{single-quote} in Lisp.@footnote{A single-quote is an
+abbreviation for the special form @code{quote}; you need not think
+about special forms now. @xref{Complications}.} Lists are the basis
+of Lisp.
@menu
* Lisp Lists:: What are lists?
three things that you really want!)
@c use code for the single apostrophe, not samp.
+@findex quote
+@cindex @code{'} for quoting
+@cindex quoting using apostrophe
+@cindex apostrophe for quoting
The single apostrophe, @code{'}, that I put in front of some of the
example lists in preceding sections is called a @dfn{quote}; when it
precedes a list, it tells Lisp to do nothing with the list, other than
@c use code for the number four, not samp.
@noindent
-You will see the number @code{4} appear in the echo area. (In the
-jargon, what you have just done is ``evaluate the list.'' The echo area
-is the line at the bottom of the screen that displays or ``echoes''
+You will see the number @code{4} appear in the echo area. (What
+you have just done is evaluate the list. The echo area
+is the line at the bottom of the screen that displays or echoes
text.) Now try the same thing with a quoted list: place the cursor
right after the following list and type @kbd{C-x C-e}:
inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
interpreter a command to evaluate the expression. The name of the Lisp
interpreter comes from the word for the task done by a human who comes
-up with the meaning of an expression---who ``interprets'' it.
+up with the meaning of an expression---who interprets it.
You can also evaluate an atom that is not part of a list---one that is
not surrounded by parentheses; again, the Lisp interpreter translates
hard, but once understood, they can point the way.
The error message is generated by a built-in GNU Emacs debugger. We
-will ``enter the debugger''. You get out of the debugger by typing @code{q}.
+will enter the debugger. You get out of the debugger by typing @code{q}.
What we will do is evaluate a list that is not quoted and does not
have a meaningful command as its first element. Here is a list almost
The slightly odd word, @samp{void-function}, is designed to cover the
way Emacs Lisp is implemented, which is that when a symbol does not
have a function definition attached to it, the place that should
-contain the instructions is ``void''.
+contain the instructions is void.
On the other hand, since we were able to add 2 plus 2 successfully, by
evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
give up on that function and produce an error message. (The interpreter
may also find itself tossed, so to speak, to a different function or it
may attempt to repeat continually what it is doing for ever and ever in
-what is called an ``infinite loop''. These actions are less common; and
+an infinite loop. These actions are less common; and
we can ignore them.) Most frequently, the interpreter returns a value.
@cindex @samp{side effect} defined
At the same time the interpreter returns a value, it may do something
else as well, such as move a cursor or copy a file; this other kind of
action is called a @dfn{side effect}. Actions that we humans think are
-important, such as printing results, are often ``side effects'' to the
-Lisp interpreter. The jargon can sound peculiar, but it turns out that
-it is fairly easy to learn to use side effects.
+important, such as printing results, are often side effects to the
+Lisp interpreter. It is fairly easy to learn to use side effects.
In summary, evaluating a symbolic expression most commonly causes the
Lisp interpreter to return a value and perhaps carry out a side effect;
Now it is easy to understand the name of the command invoked by the
keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The
letters @code{sexp} are an abbreviation for ``symbolic expression'', and
-@code{eval} is an abbreviation for ``evaluate''. The command means
-``evaluate last symbolic expression''.
+@code{eval} is an abbreviation for ``evaluate''. The command
+evaluates the last symbolic expression.
As an experiment, you can try evaluating the expression by putting the
cursor at the beginning of the next line immediately following the
@noindent
The value produced by evaluating this expression is @code{"abcdef"}.
+@cindex substring
A function such as @code{substring} uses both a string and numbers as
-arguments. The function returns a part of the string, a substring of
+arguments. The function returns a part of the string, a @dfn{substring} of
the first argument. This function takes three arguments. Its first
argument is the string of characters, the second and third arguments
are numbers that indicate the beginning (inclusive) and end
though it is made up of several words separated by spaces. Lisp counts
everything between the two quotation marks as part of the string,
including the spaces. You can think of the @code{substring} function as
-a kind of ``atom smasher'' since it takes an otherwise indivisible atom
+a kind of atom smasher since it takes an otherwise indivisible atom
and extracts a part. However, @code{substring} is only able to extract
a substring from an argument that is a string, not from another type of
atom such as a number or symbol.
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,
specifically a list, attached to it; or, expressed another way,
-the symbol is set to ``point'' to the list.
+the symbol is set to point to the list.
@node Counting
@subsection Counting
Then the instructions in the function definition are carried out.
@item
-A single quotation mark,
-@ifinfo
-'
-@end ifinfo
-@ifnotinfo
-@code{'}
-@end ifnotinfo
-, tells the Lisp interpreter that it should
+A single-quote @samp{'} tells the Lisp interpreter that it should
return the following expression as written, and not evaluate it as it
would if the quote were not there.
@item
A function always returns a value when it is evaluated (unless it gets
-an error); in addition, it may also carry out some action called a
-``side effect''. In many cases, a function's primary purpose is to
+an error); in addition, it may also carry out some action that is a
+side effect. In many cases, a function's primary purpose is to
create a side effect.
@end itemize
Also, we have just introduced another jargon term, the word @dfn{call}.
When you evaluate a list in which the first symbol is a function, you
are calling that function. The use of the term comes from the notion of
-the function as an entity that can do something for you if you ``call''
+the function as an entity that can do something for you if you call
it---just as a plumber is an entity who can fix a leak if you call him
or her.
@end smallexample
@noindent
-As I write this, the value of @code{point} is 65724. The @code{point}
+As I write this, the value of point is 65724. The @code{point}
function is frequently used in some of the examples later in this
book.
@noindent
The symbol @code{number}, specified in the function definition in the
-next section, is given or ``bound to'' the value 3 in the actual use of
+next section, is bound to the value 3 in the actual use of
the function. Note that although @code{number} was inside parentheses
in the function definition, the argument passed to the
@code{multiply-by-seven} function is not in parentheses. The
If you evaluate this example, you are likely to get an error message.
(Go ahead, try it!) This is because we have written the function
definition, but not yet told the computer about the definition---we have
-not yet installed (or ``loaded'') the function definition in Emacs.
+not yet loaded the function definition in Emacs.
Installing a function is the process that tells the Lisp interpreter the
definition of the function. Installation is described in the next
section.
@smallexample
@group
multiply-by-seven is a Lisp function.
+
(multiply-by-seven NUMBER)
Multiply NUMBER by seven.
by seven. It produces the same answer, but by a different path. At
the same time, we will add a comment to the code; a comment is text
that the Lisp interpreter ignores, but that a human reader may find
-useful or enlightening. The comment is that this is the ``second
-version''.
+useful or enlightening. The comment is that this is the second
+version.
@smallexample
@group
(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
to a key.)
-A prefix argument is passed to an interactive function by typing the
+A @dfn{prefix argument} is passed to an interactive function by typing the
@key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
type @kbd{C-u} without a number, it defaults to 4).
Consider the function @code{zap-to-char}. Its interactive expression
is
+@c FIXME: the interactive expression of zap-to-char has been changed
+@c (in 2012-04-10).
+
@smallexample
(interactive "p\ncZap to char: ")
@end smallexample
The first part of the argument to @code{interactive} is @samp{p}, with
which you are already familiar. This argument tells Emacs to
-interpret a ``prefix'', as a number to be passed to the function. You
+interpret a prefix, as a number to be passed to the function. You
can specify a prefix either by typing @kbd{C-u} followed by a number
or by typing @key{META} followed by a number. The prefix is the
number of specified characters. Thus, if your prefix is three and the
that is temporary and local. The values set by @code{let} are
automatically undone when the @code{let} is finished. The setting
only affects expressions that are inside the bounds of the @code{let}
-expression. In computer science jargon, we would say ``the binding of
+expression. In computer science jargon, we would say the binding of
a symbol is visible only in functions called in the @code{let} form;
-in Emacs Lisp, scoping is dynamic, not lexical.''
+in Emacs Lisp, scoping is dynamic, not lexical.
@code{let} can create more than one variable at once. Also,
@code{let} gives each variable it creates an initial value, either a
-value specified by you, or @code{nil}. (In the jargon, this is called
-``binding the variable to the value''.) After @code{let} has created
+value specified by you, or @code{nil}. (In the jargon, this is
+binding the variable to the value.) After @code{let} has created
and bound the variables, it executes the code in the body of the
@code{let}, and returns the value of the last expression in the body,
as the value of the whole @code{let} expression. (``Execute'' is a jargon
@smallexample
@group
-(let ((zebra 'stripes)
- (tiger 'fierce))
+(let ((zebra "stripes")
+ (tiger "fierce"))
(message "One kind of animal has %s and another is %s."
zebra tiger))
@end group
@end smallexample
-Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}.
+Here, the varlist is @code{((zebra "stripes") (tiger "fierce"))}.
The two variables are @code{zebra} and @code{tiger}. Each variable is
the first element of a two-element list and each value is the second
element of its two-element list. In the varlist, Emacs binds the
-variable @code{zebra} to the value @code{stripes}@footnote{According
+variable @code{zebra} to the value @code{"stripes"}@footnote{According
to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
become impossibly dangerous as they grow older'' but the claim here is
that they do not become fierce like a tiger. (1997, W. W. Norton and
Co., ISBN 0-393-03894-2, page 171)}, and binds the
-variable @code{tiger} to the value @code{fierce}. In this example,
-both values are symbols preceded by a quote. The values could just as
-well have been another list or a string. The body of the @code{let}
+variable @code{tiger} to the value @code{"fierce"}. In this example,
+both values are strings. The values could just as well have been
+another list or a symbol. The body of the @code{let}
follows after the list holding the variables. In this example, the
body is a list that uses the @code{message} function to print a string
in the echo area.
included here. It is used, for example, in the code for the
function @code{beginning-of-buffer}.
-The basic idea behind an @code{if}, is that ``@emph{if} a test is true,
-@emph{then} an expression is evaluated.'' If the test is not true, the
+The basic idea behind an @code{if}, is that @emph{if} a test is true,
+@emph{then} an expression is evaluated. If the test is not true, the
expression is not evaluated. For example, you might make a decision
such as, ``if it is warm and sunny, then go to the beach!''
Also, when an @code{if} expression is written, the true-or-false-test
is usually written on the same line as the symbol @code{if}, but the
-action to carry out if the test is true, the ``then-part'', is written
+action to carry out if the test is true, the then-part, is written
on the second and subsequent lines. This makes the @code{if}
expression easier to read.
For example, the value may be bound to an argument of a function
definition. In the following function definition, the character of the
animal is a value that is passed to the function. If the value bound to
-@code{characteristic} is @code{fierce}, then the message, @samp{It's a
+@code{characteristic} is @code{"fierce"}, then the message, @samp{It is a
tiger!} will be printed; otherwise, @code{nil} will be returned.
@smallexample
@group
(defun type-of-animal (characteristic)
"Print message in echo area depending on CHARACTERISTIC.
-If the CHARACTERISTIC is the symbol `fierce',
+If the CHARACTERISTIC is the string \"fierce\",
then warn of a tiger."
- (if (equal characteristic 'fierce)
- (message "It's a tiger!")))
+ (if (equal characteristic "fierce")
+ (message "It is a tiger!")))
@end group
@end smallexample
@smallexample
@group
-(type-of-animal 'fierce)
+(type-of-animal "fierce")
-(type-of-animal 'zebra)
+(type-of-animal "striped")
@end group
@end smallexample
@c Following sentences rewritten to prevent overfull hbox.
@noindent
-When you evaluate @code{(type-of-animal 'fierce)}, you will see the
-following message printed in the echo area: @code{"It's a tiger!"}; and
-when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil}
+When you evaluate @code{(type-of-animal "fierce")}, you will see the
+following message printed in the echo area: @code{"It is a tiger!"}; and
+when you evaluate @code{(type-of-animal "striped")} you will see @code{nil}
printed in the echo area.
@node type-of-animal in detail
@group
(defun type-of-animal (characteristic)
"Print message in echo area depending on CHARACTERISTIC.
-If the CHARACTERISTIC is the symbol `fierce',
+If the CHARACTERISTIC is the string \"fierce\",
then warn of a tiger."
@var{body: the} @code{if} @var{expression})
@end group
@smallexample
@group
-(if (equal characteristic 'fierce)
- (message "It's a tiger!")))
+(if (equal characteristic "fierce")
+ (message "It is a tiger!")))
@end group
@end smallexample
Here, the true-or-false-test is the expression:
@smallexample
-(equal characteristic 'fierce)
+(equal characteristic "fierce")
@end smallexample
@noindent
In Lisp, @code{equal} is a function that determines whether its first
argument is equal to its second argument. The second argument is the
-quoted symbol @code{'fierce} and the first argument is the value of the
+string @code{"fierce"} and the first argument is the value of the
symbol @code{characteristic}---in other words, the argument passed to
this function.
In the first exercise of @code{type-of-animal}, the argument
-@code{fierce} is passed to @code{type-of-animal}. Since @code{fierce}
-is equal to @code{fierce}, the expression, @code{(equal characteristic
-'fierce)}, returns a value of true. When this happens, the @code{if}
+@code{"fierce"} is passed to @code{type-of-animal}. Since @code{"fierce"}
+is equal to @code{"fierce"}, the expression, @code{(equal characteristic
+"fierce")}, returns a value of true. When this happens, the @code{if}
evaluates the second argument or then-part of the @code{if}:
-@code{(message "It's tiger!")}.
+@code{(message "It is a tiger!")}.
On the other hand, in the second exercise of @code{type-of-animal}, the
-argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra}
-is not equal to @code{fierce}, so the then-part is not evaluated and
+argument @code{"striped"} is passed to @code{type-of-animal}. @code{"striped"}
+is not equal to @code{"fierce"}, so the then-part is not evaluated and
@code{nil} is returned by the @code{if} expression.
@node else
@group
(defun type-of-animal (characteristic) ; @r{Second version.}
"Print message in echo area depending on CHARACTERISTIC.
-If the CHARACTERISTIC is the symbol `fierce',
-then warn of a tiger;
-else say it's not fierce."
- (if (equal characteristic 'fierce)
- (message "It's a tiger!")
- (message "It's not fierce!")))
+If the CHARACTERISTIC is the string \"fierce\",
+then warn of a tiger; else say it is not fierce."
+ (if (equal characteristic "fierce")
+ (message "It is a tiger!")
+ (message "It is not fierce!")))
@end group
@end smallexample
@sp 1
@smallexample
@group
-(type-of-animal 'fierce)
+(type-of-animal "fierce")
-(type-of-animal 'zebra)
+(type-of-animal "striped")
@end group
@end smallexample
@c Following sentence rewritten to prevent overfull hbox.
@noindent
-When you evaluate @code{(type-of-animal 'fierce)}, you will see the
-following message printed in the echo area: @code{"It's a tiger!"}; but
-when you evaluate @code{(type-of-animal 'zebra)}, you will see
-@code{"It's not fierce!"}.
+When you evaluate @code{(type-of-animal "fierce")}, you will see the
+following message printed in the echo area: @code{"It is a tiger!"}; but
+when you evaluate @code{(type-of-animal "striped")}, you will see
+@code{"It is not fierce!"}.
-(Of course, if the @var{characteristic} were @code{ferocious}, the
-message @code{"It's not fierce!"} would be printed; and it would be
+(Of course, if the @var{characteristic} were @code{"ferocious"}, the
+message @code{"It is not fierce!"} would be printed; and it would be
misleading! When you write code, you need to take into account the
possibility that some such argument will be tested by the @code{if}
and write your program accordingly.)
@section @code{save-excursion}
@findex save-excursion
@cindex Region, what it is
-@cindex Preserving point, mark, and buffer
-@cindex Point, mark, buffer preservation
+@cindex Preserving point and buffer
+@cindex Point and buffer preservation
@findex point
@findex mark
@code{center-region}, @code{count-lines-region}, @code{kill-region}, and
@code{print-region}.
-The @code{save-excursion} special form saves the locations of point and
+The @code{save-excursion} special form saves the location of point and
restores this position after the code within the body of the
special form is evaluated by the Lisp interpreter. Thus, if point were
in the beginning of a piece of text and some code moved point to the end
as the value of the @code{save-excursion} function. The other
expressions in the body are evaluated only for their side effects; and
@code{save-excursion} itself is used only for its side effect (which
-is restoring the positions of point and mark).
+is restoring the position of point).
@need 1250
In more detail, the template for a @code{save-excursion} expression
the definition.
@need 1250
-For example, in an early version of Emacs, the function definition was
-as follows. (It is slightly more complex now that it seeks the first
-non-whitespace character rather than the first visible character.)
+For example, in Emacs the function definition of
+@code{dired-unmark-all-marks} is as follows.
@smallexample
@group
-(defun back-to-indentation ()
- "Move point to first visible character on line."
+(defun dired-unmark-all-marks ()
+ "Remove all marks from all files in the Dired buffer."
(interactive)
- (beginning-of-line 1)
- (skip-chars-forward " \t"))
+ (dired-unmark-all-files ?\r))
@end group
@end smallexample
-@ignore
-In GNU Emacs 22,
-
-(defun backward-to-indentation (&optional arg)
- "Move backward ARG lines and position at first nonblank character."
- (interactive "p")
- (forward-line (- (or arg 1)))
- (skip-chars-forward " \t"))
-
-(defun back-to-indentation ()
- "Move point to the first non-whitespace character on this line."
- (interactive)
- (beginning-of-line 1)
- (skip-syntax-forward " " (line-end-position))
- ;; Move back over chars that have whitespace syntax but have the p flag.
- (backward-prefix-chars))
-@end ignore
-
@item interactive
Declare to the interpreter that the function can be used
interactively. This special form may be followed by a string with one
Lisp, and C, and it works with non-programming text as well. For
example, @code{find-tag} will jump to the various nodes in the
Texinfo source file of this document.
-The @code{find-tag} function depends on ``tags tables'' that record
+The @code{find-tag} function depends on @dfn{tags tables} that record
the locations of the functions, variables, and other items to which
@code{find-tag} jumps.
@cindex TAGS table, specifying
@findex find-tag
Depending on how the initial default values of your copy of Emacs are
-set, you may also need to specify the location of your ``tags table'',
+set, you may also need to specify the location of your tags table,
which is a file called @file{TAGS}. For example, if you are
interested in Emacs sources, the tags table you will most likely want,
if it has already been created for you, will be in a subdirectory of
is set at the end of the buffer. The whole buffer is, therefore, the
region.
+@c FIXME: the definition of append-to-buffer has been changed (in
+@c 2010-03-30).
@node append-to-buffer
@section The Definition of @code{append-to-buffer}
@findex append-to-buffer
The @code{append-to-buffer} command uses the
@code{insert-buffer-substring} function to copy the region.
@code{insert-buffer-substring} is described by its name: it takes a
-string of characters from part of a buffer, a ``substring'', and
-inserts them into another buffer.
+substring from a buffer, and inserts it into another buffer.
Most of @code{append-to-buffer} is
concerned with setting up the conditions for
You can imagine yourself at a conference where an usher is wandering
around holding a list with your name on it and looking for you: the
-usher is ``bound'' to your name, not to you; but when the usher finds
-you and takes your arm, the usher becomes ``bound'' to you.
+usher is bound to your name, not to you; but when the usher finds
+you and takes your arm, the usher becomes bound to you.
@need 800
In Lisp, you might describe this situation like this:
@noindent
@code{not} is a function that returns true if its argument is false
and false if its argument is true. So if @code{(bufferp buffer)}
-returns true, the @code{not} expression returns false and vice versa:
-what is ``not true'' is false and what is ``not false'' is true.
+returns true, the @code{not} expression returns false and vice versa.
Using this test, the @code{if} expression works as follows: when the
value of the variable @code{buffer} is actually a buffer rather than
buffer, not the accessible part. The computation makes much more
sense when it handles just the accessible part. (@xref{Narrowing &
Widening, , Narrowing and Widening}, for more information on focusing
-attention to an ``accessible'' part.)
+attention to an accessible part.)
@need 800
The line looks like this:
The first argument is @code{(prefix-numeric-value arg)}. When
@code{"P"} is used as the argument for @code{interactive}, the value
-passed to the function as its argument is passed a ``raw prefix
-argument'', and not a number. (It is a number in a list.) To perform
+passed to the function as its argument is passed a @dfn{raw prefix
+argument}, and not a number. (It is a number in a list.) To perform
the arithmetic, a conversion is necessary, and
@code{prefix-numeric-value} does the job.
perhaps, not necessary, but which, if it did not occur, would be sure
to draw complaints. (The @code{(not (consp arg))} portion is so that
if you specify the command with a @kbd{C-u}, but without a number,
-that is to say, if the ``raw prefix argument'' is simply a cons cell,
+that is to say, if the raw prefix argument is simply a cons cell,
the command does not put you at the beginning of the second line.)
@node Second Buffer Related Review
argument, if desired.
@item prefix-numeric-value
-Convert the ``raw prefix argument'' produced by @code{(interactive
+Convert the raw prefix argument produced by @code{(interactive
"P")} to a numeric value.
@item forward-line
they are applied. This is very important for how they are used.
Also, in the first chapter, in the discussion about atoms, I said that
-in Lisp, ``certain kinds of atom, such as an array, can be separated
+in Lisp, certain kinds of atom, such as an array, can be separated
into parts; but the mechanism for doing this is different from the
mechanism for splitting a list. As far as Lisp is concerned, the
-atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The
+atoms of a list are unsplittable. (@xref{Lisp Atoms}.) The
@code{car} and @code{cdr} functions are used for splitting lists and
are considered fundamental to Lisp. Since they cannot split or gain
access to the parts of an array, an array is considered an atom.
list in which the element is followed by the elements of the original
list.
-We often say that ``@code{cons} puts a new element at the beginning of
-a list; it attaches or pushes elements onto the list'', but this
+We often say that @code{cons} puts a new element at the beginning of
+a list, or that it attaches or pushes elements onto the list, but this
phrasing can be misleading, since @code{cons} does not change an
existing list, but creates a new one.
Note that the elements are numbered from zero, not one. That is to
say, the first element of a list, its @sc{car} is the zeroth element.
-This is called ``zero-based'' counting and often bothers people who
+This zero-based counting often bothers people who
are accustomed to the first element in a list being number one, which
-is ``one-based''.
+is one-based.
@need 1250
For example:
@noindent
If you evaluate this expression, the list @code{(cat dog)} will appear
in the echo area. This is the value returned by the function. The
-result we are interested in is the ``side effect'', which we can see by
+result we are interested in is the side effect, which we can see by
evaluating the variable @code{domesticated-animals}:
@smallexample
@cindex Erasing text
@cindex Deleting text
-Whenever you cut or clip text out of a buffer with a ``kill'' command in
+Whenever you cut or clip text out of a buffer with a @dfn{kill} command in
GNU Emacs, it is stored in a list and you can bring it back with a
-``yank'' command.
+@dfn{yank} command.
(The use of the word ``kill'' in Emacs for processes which specifically
@emph{do not} destroy the values of the entities is an unfortunate
The list that holds the pieces of text is called the @dfn{kill ring}.
This chapter leads up to a description of the kill ring and how it is
used by first tracing how the @code{zap-to-char} function works. This
-function uses (or ``calls'') a function that invokes a function that
+function calls a function that invokes a function that
manipulates the kill ring. Thus, before reaching the mountains, we
climb the foothills.
The documentation is thorough. You do need to know the jargon meaning
of the word ``kill''.
+@cindex curved quotes
+@cindex curly quotes
+The version 22 documentation string for @code{zap-to-char} uses ASCII
+grave accent and apostrophe to quote a symbol, so it appears as
+@t{`case-fold-search'}. This quoting style was inspired by 1970s-era
+displays in which grave accent and apostrophe were often mirror images
+suitable for use as quotes. On most modern displays this is no longer
+true, and when these two ASCII characters appear in documentation
+strings or diagnostic message formats, Emacs typically transliterates
+them to @dfn{curved quotes} (left and right single quotation marks),
+so that the abovequoted symbol appears
+as @t{‘case-fold-search’}. Source-code strings can also simply use
+curved quotes directly.
+
@node zap-to-char interactive
@subsection The @code{interactive} Expression
two different things. First, and most simply, is the @samp{p}.
This part is separated from the next part by a newline, @samp{\n}.
The @samp{p} means that the first argument to the function will be
-passed the value of a ``processed prefix''. The prefix argument is
+passed the value of a @dfn{processed prefix}. The prefix argument is
passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If
the function is called interactively without a prefix, 1 is passed to
this argument.
character as a string.) If the search is backwards,
@code{search-forward} leaves point just before the first character in
the target. Also, @code{search-forward} returns @code{t} for true.
-(Moving point is therefore a ``side effect''.)
+(Moving point is therefore a side effect.)
@need 1250
In @code{zap-to-char}, the @code{search-forward} function looks like this:
enables you to define new control constructs and other language
features. It tells the interpreter how to compute another Lisp
expression which will in turn compute the value. In this case, the
-``other expression'' is an @code{if} expression.
+other expression is an @code{if} expression.
The @code{kill-region} function definition also has an @code{unless}
macro; it is the converse of @code{when}. The @code{unless} macro is
@code{yank-handler} is an optional argument to @code{kill-region} that
tells the @code{kill-append} and @code{kill-new} functions how deal
-with properties added to the text, such as ``bold'' or ``italics''.
+with properties added to the text, such as bold or italics.
@code{last-command} is a variable that comes with Emacs that we have
not seen before. Normally, whenever a function is executed, Emacs
almost becoming routine.
The documentation is somewhat confusing unless you remember that the
-word ``kill'' has a meaning different from usual. The ``Transient Mark''
+word ``kill'' has a meaning different from usual. The Transient Mark
and @code{interprogram-cut-function} comments explain certain
side-effects.
(Also, the function provides an optional argument called
@code{yank-handler}; when invoked, this argument tells the function
-how to deal with properties added to the text, such as ``bold'' or
-``italics''.)
+how to deal with properties added to the text, such as bold or
+italics.)
@c !!! bug in GNU Emacs 22 version of kill-append ?
It has a @code{let*} function to set the value of the first element of
@unnumberedsubsubsec The @code{kill-new} function
@findex kill-new
-@c in GNU Emacs 22, additional documentation to kill-new:
-@ignore
-Optional third arguments YANK-HANDLER controls how the STRING is later
-inserted into a buffer; see `insert-for-yank' for details.
-When a yank handler is specified, STRING must be non-empty (the yank
-handler, if non-nil, is stored as a `yank-handler' text property on STRING).
-
-When the yank handler has a non-nil PARAM element, the original STRING
-argument is not used by `insert-for-yank'. However, since Lisp code
-may access and use elements from the kill ring directly, the STRING
-argument should still be a \"useful\" string for such uses."
-@end ignore
@need 1200
-The @code{kill-new} function looks like this:
+In version 22 the @code{kill-new} function looks like this:
@smallexample
@group
The function definition has an optional @code{yank-handler} argument,
which when invoked tells the function how to deal with properties
-added to the text, such as ``bold'' or ``italics''. We will skip that.
+added to the text, such as bold or italics. We will skip that.
@need 1200
The first line of the documentation makes sense:
@end group
@group
;; @r{else}
- (push string kill-ring)
+ (push string kill-ring)
@end group
@group
- (setq kill-ring (cons string kill-ring))
(if (> (length kill-ring) kill-ring-max)
;; @r{avoid overly long kill ring}
(setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
In this case, the expression tests first to see whether
@code{menu-bar-update-yank-menu} exists as a function, and if so,
calls it. The @code{fboundp} function returns true if the symbol it
-is testing has a function definition that ``is not void''. If the
+is testing has a function definition that is not void. If the
symbol's function definition were void, we would receive an error
message, as we did when we created errors intentionally (@pxref{Making
Errors, , Generate an Error Message}).
previously clipped text. For a detailed discussion, see
@ref{kill-append function, , The @code{kill-append} function}.)
-If you then yank back the text, i.e., ``paste'' it, you get both
+If you then yank back the text, i.e., paste it, you get both
pieces of text at once. That way, if you delete two words in a row,
and then yank them back, you get both words, in their proper order,
with one yank. (The @w{@code{(< end beg))}} expression makes sure the
@item
The sixth part is nearly like the argument that follows the
@code{interactive} declaration in a function written in Lisp: a letter
-followed, perhaps, by a prompt. The only difference from the Lisp is
+followed, perhaps, by a prompt. The only difference from Lisp is
when the macro is called with no arguments. Then you write a @code{0}
-(which is a ``null string''), as in this macro.
+(which is a null string), as in this macro.
If you were to specify arguments, you would place them between
quotation marks. The C macro for @code{goto-char} includes
The seventh part is a documentation string, just like the one for a
function written in Emacs Lisp. This is written as a C comment. (When
you build Emacs, the program @command{lib-src/make-docfile} extracts
-these comments and uses them to make the ``real'' documentation.)
+these comments and uses them to make the documentation.)
@end itemize
@need 1200
In a C macro, the formal parameters come next, with a statement of
-what kind of object they are, followed by what might be called the ``body''
-of the macro. For @code{delete-and-extract-region} the ``body''
+what kind of object they are, followed by the body
+of the macro. For @code{delete-and-extract-region} the body
consists of the following four lines:
@smallexample
The @code{del_range_1} function actually deletes the text. It is a
complex function we will not look into. It updates the buffer and
does other things. However, it is worth looking at the two arguments
-passed to @code{del_range}. These are @w{@code{XINT (start)}} and
+passed to @code{del_range_1}. These are @w{@code{XINT (start)}} and
@w{@code{XINT (end)}}.
As far as the C language is concerned, @code{start} and @code{end} are
to understand, the two integers are of type @code{Lisp_Object}, which can
also be a C union instead of an integer type.}.
-In early versions of Emacs, these two numbers were thirty-two bits
-long, but the code is slowly being generalized to handle other
-lengths. Three of the available bits are used to specify the type of
-information; the remaining bits are used as ``content''.
+Integer widths depend on the machine, and are typically 32 or 64 bits.
+A few of the bits are used to specify the type of information; the
+remaining bits are used as content.
@samp{XINT} is a C macro that extracts the relevant number from the
-longer collection of bits; the three other bits are discarded.
+longer collection of bits; the type bits are discarded.
@need 800
The command in @code{delete-and-extract-region} looks like this:
where the buried treasure lies.
(In addition to its name, symbol definition, and variable value, a
-symbol has a ``drawer'' for a @dfn{property list} which can be used to
+symbol has a drawer for a @dfn{property list} which can be used to
record other information. Property lists are not discussed here; see
@ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
Reference Manual}.)
@cindex Retrieving text
@cindex Pasting text
-Whenever you cut text out of a buffer with a ``kill'' command in GNU Emacs,
-you can bring it back with a ``yank'' command. The text that is cut out of
+Whenever you cut text out of a buffer with a kill command in GNU Emacs,
+you can bring it back with a yank command. The text that is cut out of
the buffer is put in the kill ring and the yank commands insert the
appropriate contents of the kill ring back into a buffer (not necessarily
the original buffer).
make sense on reflection. The kill ring is generally thought of as the
complete structure of data that holds the information of what has recently
been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer}
-on the other hand, serves to indicate---that is, to ``point to''---that part
+on the other hand, serves to indicate---that is, to point to---that part
of the kill ring of which the first element (the @sc{car}) will be
inserted.
way to think about and then to solve problems@footnote{You can write
recursive functions to be frugal or wasteful of mental or computer
resources; as it happens, methods that people find easy---that are
-frugal of ``mental resources''---sometimes use considerable computer
+frugal of mental resources---sometimes use considerable computer
resources. Emacs was designed to run on machines that we now consider
limited and its default settings are conservative. You may want to
increase the values of @code{max-specpdl-size} and
repeats the same thing again and again, like an airplane doing a loop.
When the result of evaluating the true-or-false-test is false, the
Lisp interpreter does not evaluate the rest of the @code{while}
-expression and ``exits the loop''.
+expression and exits the loop.
Clearly, if the value returned by evaluating the first argument to
@code{while} is always true, the body following will be evaluated
to be printed in the @file{*scratch*} buffer instead of being printed
in the echo area. (Otherwise you will see something like this in your
echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
-each @samp{^J} stands for a ``newline''.)
+each @samp{^J} stands for a newline.)
@need 1500
In a recent instance of GNU Emacs, you can evaluate these expressions
equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, ,
Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
-@code{dolist} works like a @code{while} loop that ``@sc{cdr}s down a
-list'': @code{dolist} automatically shortens the list each time it
+@code{dolist} works like a @code{while} loop that @sc{cdr}s down a
+list: @code{dolist} automatically shortens the list each time it
loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
each shorter version of the list to the first of its arguments.
Like a @code{while} loop, a @code{dolist} loops. What is different is
that it automatically shortens the list each time it loops---it
-``@sc{cdr}s down the list'' on its own---and it automatically binds
+@sc{cdr}s down the list on its own---and it automatically binds
the @sc{car} of each shorter version of the list to the first of its
arguments.
@smallexample
@group
(defun triangle-using-dotimes (number-of-rows)
- "Using dotimes, add up the number of pebbles in a triangle."
+ "Using `dotimes', add up the number of pebbles in a triangle."
(let ((total 0)) ; otherwise a total is a void variable
(dotimes (number number-of-rows total)
(setq total (+ total (1+ number))))))
is not the same entity. It is different. In the jargon, it is a
different ``instance''.
-Eventually, if the program is written correctly, the ``slightly
-different arguments'' will become sufficiently different from the first
+Eventually, if the program is written correctly, the slightly
+different arguments will become sufficiently different from the first
arguments that the final instance will stop.
@menu
@code{defun} macro, you install the necessary equipment to build
robots. It is as if you were in a factory, setting up an assembly
line. Robots with the same name are built according to the same
-blueprints. So they have, as it were, the same ``model number'', but a
-different ``serial number''.
+blueprints. So they have the same model number, but a
+different serial number.
We often say that a recursive function ``calls itself''. What we mean
is that the instructions in a recursive function cause the Lisp
The @code{print-elements-recursively} function first tests whether
there is any content in the list; if there is, the function prints the
first element of the list, the @sc{car} of the list. Then the
-function ``invokes itself'', but gives itself as its argument, not the
+function invokes itself, but gives itself as its argument, not the
whole list, but the second and subsequent elements of the list, the
@sc{cdr} of the list.
When the second evaluation occurs, the @code{when} expression is
evaluated and if true, prints the first element of the list it
receives as its argument (which is the second element of the original
-list). Then the function ``calls itself'' with the @sc{cdr} of the list
+list). Then the function calls itself with the @sc{cdr} of the list
it is invoked with, which (the second time around) is the @sc{cdr} of
the @sc{cdr} of the original list.
instance of the program. The new instance is a clone of the first,
but is a separate individual.
-Each time the function ``invokes itself'', it invokes itself on a
+Each time the function invokes itself, it does so on a
shorter version of the original list. It creates a new instance that
works on a shorter list.
@end itemize
@need 1500
-Here is example:
+Here is an example:
@smallexample
@group
every element of a list and the result of that action is accumulated
with the results of performing the action on the other elements.
-This is very like the ``every'' pattern using @code{cons}, except that
+This is very like the @code{every} pattern using @code{cons}, except that
@code{cons} is not used, but some other combiner.
@need 1500
the element is acted on and the results are kept only if the element
meets a criterion.
-Again, this is very like the ``every'' pattern, except the element is
+Again, this is very like the @code{every} pattern, except the element is
skipped unless it meets a criterion.
@need 1500
The solution to the problem of deferred operations is to write in a
manner that does not defer operations@footnote{The phrase @dfn{tail
recursive} is used to describe such a process, one that uses
-``constant space''.}. This requires
+constant space.}. This requires
writing to a different pattern, often one that involves writing two
-function definitions, an ``initialization'' function and a ``helper''
+function definitions, an initialization function and a helper
function.
-The ``initialization'' function sets up the job; the ``helper'' function
+The initialization function sets up the job; the helper function
does the work.
@need 1200
@group
(defun triangle-initialization (number)
"Return the sum of the numbers 1 through NUMBER inclusive.
-This is the `initialization' component of a two function
+This is the initialization component of a two function
duo that uses recursion."
(triangle-recursive-helper 0 0 number))
@end group
@group
(defun triangle-recursive-helper (sum counter number)
"Return SUM, using COUNTER, through NUMBER inclusive.
-This is the `helper' component of a two function duo
+This is the helper component of a two function duo
that uses recursion."
(if (> counter number)
sum
@end group
@end smallexample
-The ``initialization'' function calls the first instance of the ``helper''
+The initialization function calls the first instance of the helper
function with three arguments: zero, zero, and a number which is the
number of rows in the triangle.
-The first two arguments passed to the ``helper'' function are
+The first two arguments passed to the helper function are
initialization values. These values are changed when
@code{triangle-recursive-helper} invokes new instances.@footnote{The
jargon is mildly confusing: @code{triangle-recursive-helper} uses a
process that is iterative in a procedure that is recursive. The
process is called iterative because the computer need only record the
three values, @code{sum}, @code{counter}, and @code{number}; the
-procedure is recursive because the function ``calls itself''. On the
+procedure is recursive because the function calls itself. On the
other hand, both the process and the procedure used by
@code{triangle-recursively} are called recursive. The word
``recursive'' has different meanings in the two contexts.}
character in the target. If the search is backwards, it leaves point
just before the first character in the target. You may tell
@code{re-search-forward} to return @code{t} for true. (Moving point
-is therefore a ``side effect''.)
+is therefore a side effect.)
Like @code{search-forward}, the @code{re-search-forward} function takes
four arguments:
@smallexample
@group
(defun forward-sentence (&optional arg)
- "Move forward to next `sentence-end'. With argument, repeat.
-With negative argument, move backward repeatedly to `sentence-beginning'.
+ "Move forward to next end of sentence. With argument, repeat.
+With negative argument, move backward repeatedly to start of sentence.
The variable `sentence-end' is a regular expression that matches ends of
sentences. Also, every paragraph boundary terminates sentences as well."
@code{nil}.
Next is a @code{let}. That specifies the values of two local
-variables, @code{point} and @code{sentence-end}. The local value of
+variables, @code{opoint} and @code{sentence-end}. The local value of
point, from before the search, is used in the
@code{constrain-to-field} function which handles forms and
equivalents. The @code{sentence-end} variable is set by the
evaluates the else-part. The true-or-false-test of the @code{if}
expression is the regular expression search.
-It may seem odd to have what looks like the ``real work'' of
+It may seem odd to have what looks like the real work of
the @code{forward-sentence} function buried here, but this is a common
way this kind of operation is carried out in Lisp.
@code{let*} expression. This is a different than @code{let}. The
symbol is @code{let*} not @code{let}.
+@findex let*
The @code{let*} special form is like @code{let} except that Emacs sets
each variable in sequence, one after another, and variables in the
latter part of the varlist can make use of the values to which Emacs
Lisp files in that directory.
@need 1250
-The @code{etags} program takes all the usual shell ``wildcards''. For
+The @code{etags} program takes all the usual shell wildcards. For
example, if you have two directories for which you want a single
@file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where
@file{../elisp/} is the second directory:
Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
for you the full path names of all your @file{TAGS} files. On my
system, this command lists 34 @file{TAGS} files. On the other hand, a
-``plain vanilla'' system I recently installed did not contain any
+plain vanilla system I recently installed did not contain any
@file{TAGS} files.
If the tags table you want has been created, you can use the @code{M-x
@smallexample
@group
(let* ((foo 7)
- (bar (* 3 foo)))
- (message "'bar' is %d." bar))
- @result{} 'bar' is 21.
+ (bar (* 3 foo)))
+ (message "`bar' is %d." bar))
+ @result{} ‘bar’ is 21.
@end group
@end smallexample
It indicates that the following character is interpreted differently
than usual. For example, the two characters, @samp{\n}, stand for
@samp{newline}, rather than for a backslash followed by @samp{n}. Two
-backslashes in a row stand for an ordinary, ``unspecial'' backslash, so
+backslashes in a row stand for an ordinary, unspecial backslash, so
Emacs Lisp interpreter ends of seeing a single backslash followed by a
letter. So it discovers the letter is special.)
as you expect because there are no word-constituent characters in the
region. Since it fails, we receive an error message. But we do not
want to receive an error message in this case; we want to receive the
-message that "The region does NOT have any words."
+message ``The region does NOT have any words.''
The solution to this problem is to provide @code{re-search-forward}
with a third argument of @code{t}, which causes the function to return
user.
Often, one thinks of the binding within a @code{let} expression as
-somehow secondary to the ``primary'' work of a function. But in this
-case, what you might consider the ``primary'' job of the function,
+somehow secondary to the primary work of a function. But in this
+case, what you might consider the primary job of the function,
counting words, is done within the @code{let} expression.
@need 1250
Next, we need to write the recursive counting function.
-A recursive function has at least three parts: the ``do-again-test'', the
-``next-step-expression'', and the recursive call.
+A recursive function has at least three parts: the do-again-test, the
+next-step-expression, and the recursive call.
The do-again-test determines whether the function will or will not be
called again. Since we are counting words in a region and can use a
The third part of a recursive function is the recursive call.
-Somewhere, also, we also need a part that does the ``work'' of the
+Somewhere, we also need a part that does the work of the
function, a part that does the counting. A vital part!
@need 1250
includes the problem of handling symbols as well as words.
@item
-Second, write a function to list the numbers of words in each function
+Second, write a function to list the number of words in each function
in a file. This function can use the @code{count-words-in-defun}
function.
@item
-Third, write a function to list the numbers of words in each function
+Third, write a function to list the number of words in each function
in each of several files. This entails automatically finding the
various files, switching to them, and counting the words in the
definitions within them.
function definition, the first question is (or ought to be) what are
we going to count? When we speak of ``words'' with respect to a Lisp
function definition, we are actually speaking, in large part, of
-``symbols''. For example, the following @code{multiply-by-seven}
+symbols. For example, the following @code{multiply-by-seven}
function contains the five symbols @code{defun},
@code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In
addition, in the documentation string, it contains the four words
Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
Syntax tables specify which characters belong to which categories.
-Usually, a hyphen is not specified as a ``word constituent character''.
-Instead, it is specified as being in the ``class of characters that are
-part of symbol names but not words.'' This means that the
+Usually, a hyphen is not specified as a word constituent character.
+Instead, it is specified as being in the class of characters that are
+part of symbol names but not words. This means that the
@code{@value{COUNT-WORDS}} function treats it in the same way it treats
an interword white space, which is why @code{@value{COUNT-WORDS}}
counts @samp{multiply-by-seven} as three words.
procedure has the merit of clarity, but the task is a little tricky.
@need 1200
-The first part is simple enough: the pattern must match ``at least one
-character that is a word or symbol constituent''. Thus:
+The first part is simple enough: the pattern must match at least one
+character that is a word or symbol constituent. Thus:
@smallexample
"\\(\\w\\|\\s_\\)+"
characters must be matched at least once.
However, the second part of the regexp is more difficult to design.
-What we want is to follow the first part with ``optionally one or more
-characters that are not constituents of a word or symbol''. At first,
+What we want is to follow the first part with optionally one or more
+characters that are not constituents of a word or symbol. At first,
I thought I could define this with the following:
@smallexample
According to its documentation as shown by @kbd{C-h f} (the
@code{describe-function} command), the @code{find-file-noselect}
function reads the named file into a buffer and returns the buffer.
-(Its most recent version includes an optional wildcards argument,
+(Its most recent version includes an optional @var{wildcards} argument,
too, as well as another to read a file literally and an other you
suppress warning messages. These optional arguments are irrelevant.)
@section @code{lengths-list-file} in Detail
The core of the @code{lengths-list-file} function is a @code{while}
-loop containing a function to move point forward ``defun by defun'' and
+loop containing a function to move point forward defun by defun, and
a function to count the number of words and symbols in each defun.
This core must be surrounded by functions that do various other tasks,
including finding the file, and ensuring that point starts out at the
symbols in one function definition."
@end group
@group
- (message "Working on '%s' ... " filename)
+ (message "Working on `%s' ... " filename)
(save-excursion
(let ((buffer (find-file-noselect filename))
(lengths-list))
function is usually not needed---Emacs creates a fresh buffer if none
already exists; but if a buffer visiting the file already exists Emacs
returns that one. In this case, the buffer may be narrowed and must
-be widened. If we wanted to be fully ``user-friendly'', we would
+be widened. If we wanted to be fully user-friendly, we would
arrange to save the restriction and the location of point, but we
won't.
The @code{(goto-char (point-min))} expression moves point to the
beginning of the buffer.
-Then comes a @code{while} loop in which the ``work'' of the function is
+Then comes a @code{while} loop in which the work of the function is
carried out. In the loop, Emacs determines the length of each
definition and constructs a lengths' list containing the information.
@end ifnottex
The design using a @code{while} loop is routine. The argument passed
-the function is a list of files. As we saw earlier (@pxref{Loop
+to the function is a list of files. As we saw earlier (@pxref{Loop
Example}), you can write a @code{while} loop so that the body of the
loop is evaluated if such a list contains elements, but to exit the
loop if the list is empty. For this design to work, the body of the
with recursion. A recursive version of @code{lengths-list-many-files}
is short and simple.
-The recursive function has the usual parts: the ``do-again-test'', the
-``next-step-expression'', and the recursive call. The ``do-again-test''
+The recursive function has the usual parts: the do-again-test, the
+next-step-expression, and the recursive call. The do-again-test
determines whether the function should call itself again, which it
will do if the @code{list-of-files} contains any remaining elements;
-the ``next-step-expression'' resets the @code{list-of-files} to the
+the next-step-expression resets the @code{list-of-files} to the
@sc{cdr} of itself, so eventually the list will be empty; and the
recursive call calls itself on the shorter list. The complete
function is shorter than this description!
@end ifnottex
Based on what we have done before, we can readily foresee that it
-should not be too hard to write a function that ``@sc{cdr}s'' down the
+should not be too hard to write a function that @sc{cdr}s down the
lengths' list, looks at each element, determines which length range it
is in, and increments a counter for that range.
Emacs contains a function to sort lists, called (as you might guess)
@code{sort}. The @code{sort} function takes two arguments, the list
to be sorted, and a predicate that determines whether the first of
-two list elements is ``less'' than the second.
+two list elements is less than the second.
As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
Type Object as an Argument}), a predicate is a function that
The @code{directory-files-and-attributes} function returns a list of
lists. Each of the lists within the main list consists of 13
elements. The first element is a string that contains the name of the
-file---which, in GNU/Linux, may be a ``directory file'', that is to
+file---which, in GNU/Linux, may be a @dfn{directory file}, that is to
say, a file with the special attributes of a directory. The second
element of the list is @code{t} for a directory, a string
for symbolic link (the string is the name linked to), or @code{nil}.
sub-directory and repeat its actions.
However, we should note that every directory contains a name that
-refers to itself, called @file{.}, (``dot'') and a name that refers to
-its parent directory, called @file{..} (``double dot''). (In
+refers to itself, called @file{.} (``dot''), and a name that refers to
+its parent directory, called @file{..} (``dot dot''). (In
@file{/}, the root directory, @file{..} refers to itself, since
@file{/} has no parent.) Clearly, we do not want our
@code{files-in-below-directory} function to enter those directories,
@code{while} loop to move from one filename to another within a
directory, checking what needs to be done; and we will use a recursive
call to repeat the actions on each sub-directory. The recursive
-pattern is ``accumulate''
+pattern is Accumulate
(@pxref{Accumulate}),
using @code{append} as the combiner.
(4 3 2 1)
@end smallexample
-Note that the @code{nreverse} function is ``destructive''---that is,
+Note that the @code{nreverse} function is destructive---that is,
it changes the list to which it is applied; this contrasts with the
@code{car} and @code{cdr} functions, which are non-destructive. In
this case, we do not want the original @code{defuns-per-range-list},
Since Emacs is designed to be flexible and work with all kinds of
terminals, including character-only terminals, the graph will need to
-be made from one of the ``typewriter'' symbols. An asterisk will do; as
+be made from one of the typewriter symbols. An asterisk will do; as
we enhance the graph-printing function, we can make the choice of
symbol a user option.
the word ``print'' or the word ``insert'' or the word ``column''.
Therefore, we can simply type @kbd{M-x apropos RET
print\|insert\|column RET} and look at the result. On my system, this
-command once too takes quite some time, and then produced a list of 79
+command once took quite some time, and then produced a list of 79
functions and variables. Now it does not take much time at all and
produces a list of 211 functions and variables. Scanning down the
list, the only function that looks as if it might do the job is
current element of the @code{numbers-list}. We need to construct a
list of asterisks of the right length for each call to
@code{insert-rectangle}. If this list consists solely of the requisite
-number of asterisks, then we will have position point the right number
+number of asterisks, then we will have to position point the right number
of lines above the base for the graph to print correctly. This could
be difficult.
@findex apply
We need a function that passes a list of arguments to a function.
-This function is @code{apply}. This function ``applies'' its first
+This function is @code{apply}. This function applies its first
argument (a function) to its remaining arguments, the last of which
may be a list.
without a book such as this. It is possible to discover other
functions, like @code{search-forward} or @code{insert-rectangle}, by
guessing at a part of their names and then using @code{apropos}. Even
-though its base in metaphor is clear---``apply'' its first argument to
+though its base in metaphor is clear---apply its first argument to
the rest---I doubt a novice would come up with that particular word
when using @code{apropos} or other aid. Of course, I could be wrong;
after all, the function was first named by someone who had to invent
As written, @code{column-of-graph} contains a major flaw: the symbols
used for the blank and for the marked entries in the column are
-``hard-coded'' as a space and asterisk. This is fine for a prototype,
+hard-coded as a space and asterisk. This is fine for a prototype,
but you, or another user, may wish to use other symbols. For example,
-in testing the graph function, you many want to use a period in place
+in testing the graph function, you may want to use a period in place
of the space, to make sure the point is being repositioned properly
each time the @code{insert-rectangle} function is called; or you might
want to substitute a @samp{+} sign or other symbol for the asterisk.
below the top is blank. To construct a column for a line graph, the
function first constructs a list of blanks that is one shorter than
the value, then it uses @code{cons} to attach a graph symbol to the
-list; then it uses @code{cons} again to attach the ``top blanks'' to
+list; then it uses @code{cons} again to attach the top blanks to
the list.
It is easy to see how to write such a function, but since we don't
@w{@code{(sit-for 0)}} expression in the @code{while} loop. This
expression makes the graph printing operation more interesting to
watch than it would be otherwise. The expression causes Emacs to
-``sit'' or do nothing for a zero length of time and then redraw the
+@dfn{sit} or do nothing for a zero length of time and then redraw the
screen. Placed here, it causes Emacs to redraw the screen column by
column. Without it, Emacs would not redraw the screen until the
function exits.
@findex recursive-graph-body-print
The @code{graph-body-print} function may also be written recursively.
-The recursive solution is divided into two parts: an outside ``wrapper''
+The recursive solution is divided into two parts: an outside wrapper
that uses a @code{let} expression to determine the values of several
variables that need only be found once, such as the maximum height of
the graph, and an inside function that is called recursively to print
the graph.
@need 1250
-The ``wrapper'' is uncomplicated:
+The wrapper is uncomplicated:
@smallexample
@group
@end smallexample
The recursive function is a little more difficult. It has four parts:
-the ``do-again-test'', the printing code, the recursive call, and the
-``next-step-expression''. The ``do-again-test'' is a @code{when}
+the do-again-test, the printing code, the recursive call, and the
+next-step-expression. The do-again-test is a @code{when}
expression that determines whether the @code{numbers-list} contains
any remaining elements; if it does, the function prints one column of
the graph using the printing code and calls itself again. The
function calls itself again according to the value produced by the
-``next-step-expression'' which causes the call to act on a shorter
+next-step-expression which causes the call to act on a shorter
version of the @code{numbers-list}.
@smallexample
@cindex Initialization file
``You don't have to like Emacs to like it''---this seemingly
-paradoxical statement is the secret of GNU Emacs. The plain, ``out of
-the box'' Emacs is a generic tool. Most people who use it, customize
+paradoxical statement is the secret of GNU Emacs. The plain, out-of-the-box
+Emacs is a generic tool. Most people who use it customize
it to suit themselves.
GNU Emacs is mostly written in Emacs Lisp; this means that by writing
right default for such a file, just as C mode is the right default for
editing C code. (Enough programming languages have syntaxes
that enable them to share or nearly share features, so C mode is
-now provided by CC mode, the ``C Collection''.)
+now provided by CC mode, the C Collection.)
But when you do know who is going to use Emacs---you,
yourself---then it makes sense to customize Emacs.
everyone.
Two site-wide initialization files, @file{site-load.el} and
-@file{site-init.el}, are loaded into Emacs and then ``dumped'' if a
-``dumped'' version of Emacs is created, as is most common. (Dumped
+@file{site-init.el}, are loaded into Emacs and then dumped if a
+dumped version of Emacs is created, as is most common. (Dumped
copies of Emacs load more quickly. However, once a file is loaded and
dumped, a change to it does not lead to a change in Emacs unless you
load it yourself or re-dump Emacs. @xref{Building Emacs, , Building
@end smallexample
@noindent
-and find that the group for editing files of data is called ``data''.
+and find that the group for editing files of text is called ``Text''.
Enter that group. Text Mode Hook is the first member. You can click
on its various options, such as @code{turn-on-auto-fill}, to set the
values. After you click on the button to
@node Text and Auto-fill
@section Text and Auto Fill Mode
-Now we come to the part that ``turns on'' Text mode and
+Now we come to the part that turns on Text mode and
Auto Fill mode.
@smallexample
the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs
possesses a list of extensions and specifications that it uses
automatically. In addition, Emacs looks near the last page for a
-per-buffer, ``local variables list'', if any.
+per-buffer, local variables list, if any.
@ifinfo
@xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
We are already familiar with @code{setq}. It sets the following variable,
@code{major-mode}, to the subsequent value, which is @code{text-mode}.
-The single quote mark before @code{text-mode} tells Emacs to deal directly
+The single-quote before @code{text-mode} tells Emacs to deal directly
with the @code{text-mode} symbol, not with whatever it might stand for.
@xref{set & setq, , Setting the Value of a Variable},
for a reminder of how @code{setq} works.
@code{turn-on-auto-fill} is the name of a program, that, you guessed
it!, turns on Auto Fill mode.
-Every time Emacs turns on Text mode, Emacs runs the commands ``hooked''
+Every time Emacs turns on Text mode, Emacs runs the commands hooked
onto Text mode. So every time Emacs turns on Text mode, Emacs also
turns on Auto Fill mode.
@node Mail Aliases
@section Mail Aliases
-Here is a @code{setq} that ``turns on'' mail aliases, along with more
+Here is a @code{setq} that turns on mail aliases, along with more
reminders.
@smallexample
says, in effect, ``Yes, use mail aliases.''
Mail aliases are convenient short names for long email addresses or
-for lists of email addresses. The file where you keep your ``aliases''
+for lists of email addresses. The file where you keep your aliases
is @file{~/.mailrc}. You write an alias like this:
@smallexample
@findex global-set-key
The command is @code{global-set-key}. It is followed by the
keybinding. In a @file{.emacs} file, the keybinding is written as
-shown: @code{\C-c} stands for ``control-c'', which means ``press the
-control key and the @key{c} key at the same time''. The @code{w} means
-``press the @key{w} key''. The keybinding is surrounded by double
+shown: @code{\C-c} stands for Control-C, which means to press the
+control key and the @key{c} key at the same time. The @code{w} means
+to press the @key{w} key. The keybinding is surrounded by double
quotation marks. In documentation, you would write this as
@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as
@kbd{M-c}, rather than a @key{CTRL} key, you would write
details.)
The command invoked by the keys is @code{compare-windows}. Note that
-@code{compare-windows} is preceded by a single quote; otherwise, Emacs
+@code{compare-windows} is preceded by a single-quote; otherwise, Emacs
would first try to evaluate the symbol to determine its value.
These three things, the double quotation marks, the backslash before
-the @samp{C}, and the single quote mark are necessary parts of
+the @samp{C}, and the single-quote are necessary parts of
keybinding that I tend to forget. Fortunately, I have come to
remember that I should look at my existing @file{.emacs} file, and
adapt what is there.
As for the keybinding itself: @kbd{C-c w}. This combines the prefix
key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This
set of keys, @kbd{C-c} followed by a single character, is strictly
-reserved for individuals' own use. (I call these ``own'' keys, since
+reserved for individuals' own use. (I call these @dfn{own} keys, since
these are for my own use.) You should always be able to create such a
keybinding for your own use without stomping on someone else's
keybinding. If you ever write an extension to Emacs, please avoid
taking any of these keys for public use. Create a key like @kbd{C-c
-C-w} instead. Otherwise, we will run out of ``own'' keys.
+C-w} instead. Otherwise, we will run out of own keys.
@need 1250
Here is another keybinding, with a comment:
@smallexample
@group
(defun load-library (library)
- "Load the library named LIBRARY.
-This is an interface to the function `load'."
+ "Load the Emacs Lisp library named LIBRARY.
+This is an interface to the function `load'. LIBRARY is searched
+for in `load-path', both with and without `load-suffixes' (as
+well as `load-file-rep-suffixes').
+
+See Info node `(emacs)Lisp Libraries' for more details.
+See `load-file' for a different interface to `load'."
(interactive
(list (completing-read "Load library: "
(apply-partially 'locate-file-completion-table
Rarely used functions are frequently autoloaded. The
@file{loaddefs.el} library contains thousands of autoloaded functions,
from @code{5x5} to @code{zone}. Of course, you may
-come to use a ``rare'' function frequently. When you do, you should
+come to use a rare function frequently. When you do, you should
load that function's file with a @code{load} expression in your
@file{.emacs} file.
In my @file{.emacs} file, I load 14 libraries that contain functions
that would otherwise be autoloaded. (Actually, it would have been
-better to include these files in my ``dumped'' Emacs, but I forgot.
+better to include these files in my dumped Emacs, but I forgot.
@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
Reference Manual}, and the @file{INSTALL} file for more about
dumping.)
@end group
@end smallexample
-If you want to write with Chinese ``GB'' characters, set this instead:
+If you want to write with Chinese GB characters, set this instead:
@smallexample
@group
@code{:eval} says to evaluate the following form and use the result as
a string to display. In this case, the expression displays the first
component of the full system name. The end of the first component is
-a @samp{.} (``period''), so I use the @code{string-match} function to
+a @samp{.} (period), so I use the @code{string-match} function to
tell me the length of the first component. The substring from the
zeroth character to that length is the name of the machine.
@emph{top} of the window.) @samp{%-} inserts enough dashes to fill
out the line.
-Remember, ``You don't have to like Emacs to like it''---your own
+Remember, you don't have to like Emacs to like it---your own
Emacs can have different colors, different commands, and different
keys than a default Emacs.
-On the other hand, if you want to bring up a plain ``out of the box''
+On the other hand, if you want to bring up a plain out-of-the-box
Emacs, with no customization, type:
@smallexample
long lines. As usual, you can quit the debugger by typing @kbd{q} in
the @file{*Backtrace*} buffer.)
-In practice, for a bug as simple as this, the ``Lisp error'' line will
+In practice, for a bug as simple as this, the Lisp error line will
tell you what you need to know to correct the definition. The
-function @code{1=} is ``void''.
+function @code{1=} is void.
@ignore
@need 800
an arrowhead at the left hand side of that line. The arrowhead marks
the line where the function is executing. (In the following examples,
we show the arrowhead with @samp{=>}; in a windowing system, you may
-see the arrowhead as a solid triangle in the window ``fringe''.)
+see the arrowhead as a solid triangle in the window fringe.)
@smallexample
=>@point{}(if (= number 1)
@noindent
This means the value of @code{number} is 3, which is octal three,
-hexadecimal three, and @sc{ascii} ``control-c'' (the third letter of the
+hexadecimal three, and @sc{ascii} Control-C (the third letter of the
alphabet, in case you need to know this information).
You can continue moving through the code until you reach the line with
Install the @code{@value{COUNT-WORDS}} function and then cause it to
enter the built-in debugger when you call it. Run the command on a
region containing two words. You will need to press @kbd{d} a
-remarkable number of times. On your system, is a ``hook'' called after
+remarkable number of times. On your system, is a hook called after
the command finishes? (For information on hooks, see @ref{Command
Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
Manual}.)
we have not studied: @code{skip-chars-forward}, @code{indent-to},
@code{current-column} and @code{insert-and-inherit}.
-Consider the @code{skip-chars-forward} function. (It is part of the
-function definition for @code{back-to-indentation}, which is shown in
-@ref{Review, , Review}.)
-
+Consider the @code{skip-chars-forward} function.
In GNU Emacs, you can find out more about @code{skip-chars-forward} by
typing @kbd{C-h f} (@code{describe-function}) and the name of the
function. This gives you the function documentation.
character codes; and it shows how to create a temporary buffer.
(The @code{indent-to} function is written in C rather than Emacs Lisp;
-it is a ``built-in'' function. @code{help-follow} takes you to its
+it is a built-in function. @code{help-follow} takes you to its
source as does @code{find-tag}, when properly set up.)
You can look at a function's source using @code{find-tag}, which is
@group
(defun current-kill (n &optional do-not-move)
"Rotate the yanking point by N places, and then return that kill.
-If N is zero, `interprogram-paste-function' is set, and calling it
-returns a string, then that string is added to the front of the
-kill ring and returned as the latest kill.
+If N is zero and `interprogram-paste-function' is set to a
+function that returns a string or a list of strings, and if that
+function doesn't return nil, then that string (or list) is added
+to the front of the kill ring and the string (or first string in
+the list) is returned as the latest kill.
@end group
@group
-If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
-yanking point; just return the Nth kill forward."
+If N is not zero, and if `yank-pop-change-selection' is
+non-nil, use `interprogram-cut-function' to transfer the
+kill at the new yank point into the window system selection.
+@end group
+@group
+If optional arg DO-NOT-MOVE is non-nil, then don't actually
+move the yanking point; just return the Nth kill forward."
+
(let ((interprogram-paste (and (= n 0)
interprogram-paste-function
(funcall interprogram-paste-function))))
;; text to the kill ring, so Emacs doesn't try to own the
;; selection, with identical text.
(let ((interprogram-cut-function nil))
- (kill-new interprogram-paste))
- interprogram-paste)
+ (if (listp interprogram-paste)
+ (mapc 'kill-new (nreverse interprogram-paste))
+ (kill-new interprogram-paste)))
+ (car kill-ring))
@end group
@group
(or kill-ring (error "Kill ring is empty"))
(nthcdr (mod (- n (length kill-ring-yank-pointer))
(length kill-ring))
kill-ring)))
- (or do-not-move
- (setq kill-ring-yank-pointer ARGth-kill-element))
+ (unless do-not-move
+ (setq kill-ring-yank-pointer ARGth-kill-element)
+ (when (and yank-pop-change-selection
+ (> n 0)
+ interprogram-cut-function)
+ (funcall interprogram-cut-function (car ARGth-kill-element))))
(car ARGth-kill-element)))))
@end group
@end smallexample
@code{interprogram-paste} and one if not.
@need 2000
-Let us consider the ``if not'' or else-part of the @code{current-kill}
+Let us consider the else-part of the @code{current-kill}
function. (The then-part uses the @code{kill-new} function, which
we have already described. @xref{kill-new function, , The
@code{kill-new} function}.)
even in the bowels of a computer. As it is, the code in Emacs implies
that a human who is acting virtuously, by exploring his or her
environment, is making an error. This is bad. Even though the computer
-takes the same steps as it does when there is an ``error'', a term such as
+takes the same steps as it does when there is an error, a term such as
``cancel'' would have a clearer connotation.
@ifnottex
"Reinsert (\"paste\") the last stretch of killed text.
More precisely, reinsert the stretch of killed text most recently
killed OR yanked. Put point at end, and set mark at beginning.
-With just \\[universal-argument] as argument, same but put point at
-beginning (and mark at end). With argument N, reinsert the Nth most
-recently killed stretch of killed text.
+With just \\[universal-argument] as argument, same but put point at beginning (and mark at end).
+With argument N, reinsert the Nth most recently killed stretch of killed
+text.
When this command inserts killed text into the buffer, it honors
`yank-excluded-properties' and `yank-handler' as described in the
doc string for `insert-for-yank-1', which see.
-See also the command \\[yank-pop]."
+See also the command `yank-pop' (\\[yank-pop])."
@end group
@group
(interactive "*P")
((eq arg '-) -2)
(t (1- arg)))))
(if (consp arg)
- ;; This is like exchange-point-and-mark,
- ;; but doesn't activate the mark.
+ ;; This is like exchange-point-and-mark, but doesn't activate the mark.
;; It is cleaner to avoid activation, even though the command
;; loop would deactivate the mark because we inserted text.
(goto-char (prog1 (mark t)
(* (1+ (/ 12 5)) 5)
@end smallexample
-All through this discussion, we have been using ``five'' as the value
+All through this discussion, we have been using 5 as the value
for spacing labels on the Y axis; but we may want to use some other
-value. For generality, we should replace ``five'' with a variable to
+value. For generality, we should replace 5 with a variable to
which we can assign a value. The best name I can think of for this
variable is @code{Y-axis-label-spacing}.
@group
(defun Y-axis-element (number full-Y-label-width)
"Construct a NUMBERed label element.
-A numbered element looks like this ' 5 - ',
+A numbered element looks like this ` 5 - ',
and is padded as needed so all line up with
the element for the largest number."
@end group
Height must be the maximum height of the graph.
Full width is the width of the highest label element."
;; Value of height and full-Y-label-width
-;; are passed by 'print-graph'.
+;; are passed by print-graph.
@end group
@group
(let ((start (point)))
@end smallexample
Next, we create the function to print the numbered line, starting with
-the number ``1'' under the first column:
+the number 1 under the first column:
@findex print-X-axis-numbered-line
@smallexample
@end smallexample
@noindent
-is a function definition that says ``return the value resulting from
-dividing whatever is passed to me as @code{arg} by 50''.
+is a function that returns the value resulting from
+dividing whatever is passed to it as @code{arg} by 50.
@need 1200
Earlier, for example, we had a function @code{multiply-by-seven}; it
@end group
@group
;; Value of symbol-width and full-Y-label-width
-;; are passed by 'print-graph'.
+;; are passed by print-graph.
(let* ((leading-spaces
(make-string full-Y-label-width ? ))
;; symbol-width @r{is provided by} graph-body-print
@end group
@group
- (message "Working on '%s' ... " filename)
+ (message "Working on `%s' ... " filename)
(save-excursion
(let ((buffer (find-file-noselect filename))
(lengths-list))
@group
(defun Y-axis-element (number full-Y-label-width)
"Construct a NUMBERed label element.
-A numbered element looks like this ' 5 - ',
+A numbered element looks like this ` 5 - ',
and is padded as needed so all line up with
the element for the largest number."
@end group