-\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
@c sethtmlfilename emacs-lisp-intro.html
@settitle Programming in Emacs Lisp
-@documentencoding UTF-8
+@include docstyle.texi
@syncodeindex vr cp
@syncodeindex fn cp
@finalout
@c @set largebook
@c (Note: if you edit the book so as to change the length of the
-@c table of contents, you may have to change the value of `pageno' below.)
+@c table of contents, you may have to change the value of 'pageno' below.)
@c <<<< For hard copy printing, this file is now
@c set for smallbook, which works for all sizes
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
@end quotation
@end copying
-@c half title; two lines here, so do not use `shorttitlepage'
+@c half title; two lines here, so do not use 'shorttitlepage'
@tex
{\begingroup%
\hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
* if:: What if?
* else:: If--then--else expressions.
* Truth & Falsehood:: What Lisp considers false and true.
-* save-excursion:: Keeping track of point, mark, and buffer.
+* save-excursion:: Keeping track of point and buffer.
* Review::
* defun Exercises::
* Point and mark:: A review of various locations.
* Template for save-excursion::
-A Few Buffer--Related Functions
+A Few Buffer-Related Functions
* Finding More:: How to find more information.
* simplified-beginning-of-buffer:: Shows @code{goto-char},
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,
To the untutored eye, Lisp is a strange programming language. In Lisp
code there are parentheses everywhere. Some people even claim that
-the name stands for `Lots of Isolated Silly Parentheses'. But the
+the name stands for ``Lots of Isolated Silly Parentheses''. But the
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?
In Lisp, what we have been calling words are called @dfn{atoms}. This
term comes from the historical meaning of the word atom, which means
-`indivisible'. As far as Lisp is concerned, the words we have been
+``indivisible''. As far as Lisp is concerned, the words we have been
using in the lists cannot be divided into any smaller parts and still
mean the same thing as part of a program; likewise with numbers and
single character symbols like @samp{+}. On the other hand, unlike an
@noindent
In Lisp, all of the quoted text including the punctuation mark and the
blank spaces is a single atom. This kind of atom is called a
-@dfn{string} (for `string of characters') and is the sort of thing that
+@dfn{string} (for ``string of characters'') and is the sort of thing that
is used for messages that a computer can print for a human to read.
Strings are a different kind of atom than numbers or symbols and are
used differently.
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
You read the @file{*Backtrace*} buffer from the bottom up; it tells
you what Emacs did. When you typed @kbd{C-x C-e}, you made an
interactive call to the command @code{eval-last-sexp}. @code{eval} is
-an abbreviation for `evaluate' and @code{sexp} is an abbreviation for
-`symbolic expression'. The command means `evaluate last symbolic
-expression', which is the expression just before your cursor.
+an abbreviation for ``evaluate'' and @code{sexp} is an abbreviation for
+``symbolic expression''. The command means ``evaluate last symbolic
+expression'', which is the expression just before your cursor.
Each line above tells you what the Lisp interpreter evaluated next.
The most recent action is at the top. The buffer is called the
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
When the Lisp interpreter works on an expression, the term for the
activity is called @dfn{evaluation}. We say that the interpreter
-`evaluates the expression'. I've used this term several times before.
-The word comes from its use in everyday language, `to ascertain the
-value or amount of; to appraise', according to @cite{Webster's New
+``evaluates the expression''. I've used this term several times before.
+The word comes from its use in everyday language, ``to ascertain the
+value or amount of; to appraise'', according to @cite{Webster's New
Collegiate Dictionary}.
@menu
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'.
+letters @code{sexp} are an abbreviation for ``symbolic expression'', and
+@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
This backtrace is different from the very first error message we saw,
which said, @samp{Debugger entered--Lisp error: (void-function this)}.
In this case, the function does not have a value as a variable; while
-in the other error message, the function (the word `this') did not
+in the other error message, the function (the word @samp{this}) did not
have a definition.
In this experiment with the @code{+}, what we did was cause the Lisp
function @code{+}. These numbers are the information that is given to
or @dfn{passed} to the function.
-The word `argument' comes from the way it is used in mathematics and
+The word ``argument'' comes from the way it is used in mathematics and
does not refer to a disputation between two people; instead it refers to
the information presented to the function, in this case, to the
@code{+}. In Lisp, the arguments to a function are the atoms or lists
that follow the function. The values returned by the evaluation of
these atoms or lists are passed to the function. Different functions
require different numbers of arguments; some functions require none at
-all.@footnote{It is curious to track the path by which the word `argument'
+all.@footnote{It is curious to track the path by which the word ``argument''
came to have two different meanings, one in mathematics and the other in
everyday English. According to the @cite{Oxford English Dictionary},
the word derives from the Latin for @samp{to make clear, prove}; thus it
-came to mean, by one thread of derivation, `the evidence offered as
-proof', which is to say, `the information offered', which led to its
+came to mean, by one thread of derivation, ``the evidence offered as
+proof'', which is to say, ``the information offered'', which led to its
meaning in Lisp. But in the other thread of derivation, it came to mean
-`to assert in a manner against which others may make counter
-assertions', which led to the meaning of the word as a disputation.
+``to assert in a manner against which others may make counter
+assertions'', which led to the meaning of the word as a disputation.
(Note here that the English word has two different definitions attached
to it at the same time. By contrast, in Emacs Lisp, a symbol cannot
have two different function definitions at the same time.)}
@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 and end of the substring. The
-numbers are a count of the number of characters (including spaces and
-punctuation) from the beginning of the string.
+argument is the string of characters, the second and third arguments
+are numbers that indicate the beginning (inclusive) and end
+(exclusive) of the substring. The numbers are a count of the number
+of characters (including spaces and punctuation) from the beginning of
+the string. Note that the characters in a string are numbered from
+zero, not one.
@need 800
For example, if you evaluate the following:
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.
number of arguments. (The @code{*} is the symbol for multiplication.)
This can be seen by evaluating each of the following expressions in
the usual way. What you will see in the echo area is printed in this
-text after @samp{@result{}}, which you may read as `evaluates to'.
+text after @samp{@result{}}, which you may read as ``evaluates to''.
@need 1250
In the first set, the functions have no arguments:
The @samp{p} of @code{number-or-marker-p} is the embodiment of a
practice started in the early days of Lisp programming. The @samp{p}
-stands for `predicate'. In the jargon used by the early Lisp
+stands for ``predicate''. In the jargon used by the early Lisp
researchers, a predicate refers to a function to determine whether some
property is true or false. So the @samp{p} tells us that
@code{number-or-marker-p} is the name of a function that determines
not have fit on a page; and humans find it easier to read nicely
formatted lists.)
-Although I have been using the term `assign', there is another way of
+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
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
+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
file. In Info, the buffer name is @file{"*info*"}. Info does not
point to any file, so the result of evaluating
@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
-from the Latin word for `nothing'; in this case, it means that the
+from the Latin word for ``nothing''; in this case, it means that the
buffer is not associated with any file. (In Lisp, @code{nil} is also
-used to mean `false' and is a synonym for the empty list, @code{()}.)
+used to mean ``false'' and is a synonym for the empty list, @code{()}.)
When I am writing, the name of my buffer is
@file{"introduction.texinfo"}. The name of the file to which it
since the computer is not as smart as a person.
@cindex Buffer, history of word
-The word `buffer', by the way, comes from the meaning of the word as a
+The word ``buffer'', by the way, comes from the meaning of the word as a
cushion that deadens the force of a collision. In early computers, a
buffer cushioned the interaction between files and the computer's
central processing unit. The drums or tapes that held a file and the
@c noindent
In this case, the first argument to @code{other-buffer} tells it which
buffer to skip---the current one---and the second argument tells
-@code{other-buffer} it is OK to switch to a visible buffer.
-In regular use, @code{switch-to-buffer} takes you to an invisible
-window since you would most likely use @kbd{C-x o} (@code{other-window})
-to go to another visible buffer.}
+@code{other-buffer} it is OK to switch to a visible buffer. In
+regular use, @code{switch-to-buffer} takes you to a buffer not visible
+in windows since you would most likely use @kbd{C-x o}
+(@code{other-window}) to go to another visible buffer.}
In the programming examples in later sections of this document, you will
see the function @code{set-buffer} more often than
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.
* if:: What if?
* else:: If--then--else expressions.
* Truth & Falsehood:: What Lisp considers false and true.
-* save-excursion:: Keeping track of point, mark, and buffer.
+* save-excursion:: Keeping track of point and buffer.
* Review::
* defun Exercises::
@end menu
Instead of choosing the word @code{number} for the name of the argument,
I could have picked any other name. For example, I could have chosen
-the word @code{multiplicand}. I picked the word `number' because it
+the word @code{multiplicand}. I picked the word ``number'' because it
tells what kind of value is intended for this slot; but I could just as
-well have chosen the word `multiplicand' to indicate the role that the
+well have chosen the word ``multiplicand'' to indicate the role that the
value placed in this slot will play in the workings of the function. I
could have called it @code{foogle}, but that would have been a bad
choice because it would not tell humans what it means. The choice of
you use in an argument list is private to that particular definition.
In that definition, the name refers to a different entity than any use
of the same name outside the function definition. Suppose you have a
-nick-name `Shorty' in your family; when your family members refer to
-`Shorty', they mean you. But outside your family, in a movie, for
-example, the name `Shorty' refers to someone else. Because a name in an
+nick-name ``Shorty'' in your family; when your family members refer to
+``Shorty'', they mean you. But outside your family, in a movie, for
+example, the name ``Shorty'' refers to someone else. Because a name in an
argument list is private to the function definition, you can change the
value of such a symbol inside the body of a function without changing
its value outside the function. The effect is similar to that produced
by a @code{let} expression. (@xref{let, , @code{let}}.)
@ignore
-Note also that we discuss the word `number' in two different ways: as a
+Note also that we discuss the word ``number'' in two different ways: as a
symbol that appears in the code, and as the name of something that will
be replaced by a something else during the evaluation of the function.
In the first case, @code{number} is a symbol, not a number; it happens
@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
To understand why the @code{let} special form is necessary, consider
the situation in which you own a home that you generally refer to as
-`the house', as in the sentence, ``The house needs painting.'' If you
-are visiting a friend and your host refers to `the house', he is
+``the house'', as in the sentence, ``The house needs painting.'' If you
+are visiting a friend and your host refers to ``the house'', he is
likely to be referring to @emph{his} house, not yours, that is, to a
different house.
The @code{let} special form prevents confusion. @code{let} creates a
name for a @dfn{local variable} that overshadows any use of the same
name outside the @code{let} expression. This is like understanding
-that whenever your host refers to `the house', he means his house, not
+that whenever your host refers to ``the house'', he means his house, not
yours. (Symbols used in argument lists work the same way.
@xref{defun, , The @code{defun} Macro}.)
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
+as the value of the whole @code{let} expression. (``Execute'' is a jargon
term that means to evaluate a list; it comes from the use of the word
-meaning `to give practical effect to' (@cite{Oxford English
+meaning ``to give practical effect to'' (@cite{Oxford English
Dictionary}). Since you evaluate an expression to perform an action,
-`execute' has evolved as a synonym to `evaluate'.)
+``execute'' has evolved as a synonym to ``evaluate''.)
@node Parts of let Expression
@subsection The Parts of a @code{let} Expression
@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!''
@cindex @samp{if-part} defined
@cindex @samp{then-part} defined
-An @code{if} expression written in Lisp does not use the word `then';
+An @code{if} expression written in Lisp does not use the word ``then'';
the test and the action are the second and third elements of the list
whose first element is @code{if}. Nonetheless, the test part of an
@code{if} expression is often called the @dfn{if-part} and the second
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.)
@findex nil
There is an important aspect to the truth test in an @code{if}
-expression. So far, we have spoken of `true' and `false' as values of
+expression. So far, we have spoken of ``true'' and ``false'' as values of
predicates as if they were new kinds of Emacs Lisp objects. In fact,
-`false' is just our old friend @code{nil}. Anything else---anything
-at all---is `true'.
+``false'' is just our old friend @code{nil}. Anything else---anything
+at all---is ``true''.
The expression that tests for truth is interpreted as @dfn{true}
if the result of evaluating it is a value that is not @code{nil}. In
@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
that we will discuss in this chapter.
In Emacs Lisp programs used for editing, the @code{save-excursion}
-function is very common. It saves the location of point and mark,
-executes the body of the function, and then restores point and mark to
-their previous positions if their locations were changed. Its primary
+function is very common. It saves the location of point,
+executes the body of the function, and then restores point to
+its previous position if its location was changed. Its primary
purpose is to keep the user from being surprised and disturbed by
-unexpected movement of point or mark.
+unexpected movement of point.
@menu
* Point and mark:: A review of various locations.
@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
-mark and restores those positions after the code within the body of the
+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
of the buffer, the @code{save-excursion} would put point back to where
workings even though a user would not expect this. For example,
@code{count-lines-region} moves point. To prevent the user from being
bothered by jumps that are both unexpected and (from the user's point of
-view) unnecessary, @code{save-excursion} is often used to keep point and
-mark in the location expected by the user. The use of
+view) unnecessary, @code{save-excursion} is often used to keep point in
+the location expected by the user. The use of
@code{save-excursion} is good housekeeping.
To make sure the house stays clean, @code{save-excursion} restores the
-values of point and mark even if something goes wrong in the code inside
+value of point even if something goes wrong in the code inside
of it (or, to be more precise and to use the proper jargon, ``in case of
abnormal exit''). This feature is very helpful.
-In addition to recording the values of point and mark,
+In addition to recording the value of point,
@code{save-excursion} keeps track of the current buffer, and restores
it, too. This means you can write code that will change the buffer and
have @code{save-excursion} switch you back to the original buffer.
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
The name of an existing file.
@item p
-The numeric prefix argument. (Note that this `p' is lower case.)
+The numeric prefix argument. (Note that this @code{p} is lower case.)
@item r
Point and the mark, as two numeric arguments, smallest first. This
@end smallexample
@item save-excursion
-Record the values of point and mark and the current buffer before
-evaluating the body of this special form. Restore the values of point
-and mark and buffer afterward.
+Record the values of point and the current buffer before
+evaluating the body of this special form. Restore the value of point and
+buffer afterward.
@need 1250
For example,
@item equal
@itemx eq
Test whether two objects are the same. @code{equal} uses one meaning
-of the word `same' and @code{eq} uses another: @code{equal} returns
+of the word ``same'' and @code{eq} uses another: @code{equal} returns
true if the two objects have a similar structure and contents, such as
two copies of the same book. On the other hand, @code{eq}, returns
true if both arguments are actually the same object.
functions that correspond to @var{>}, @code{>=}, or @code{<=}.
@item message
-Print a message in the echo area. The first argument is a string that
+Print a message in the echo area. The first argument is a string that
can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
arguments that follow the string. The argument used by @samp{%s} must
be a string or a symbol; the argument used by @samp{%d} must be a
@end itemize
@node Buffer Walk Through
-@chapter A Few Buffer--Related Functions
+@chapter A Few Buffer-Related Functions
In this chapter we study in detail several of the functions used in GNU
Emacs. This is called a ``walk-through''. These functions are used as
Put point into the name of the file that contains the function and
press the @key{RET} key. In this case, @key{RET} means
-@code{push-button} rather than `return' or `enter'. Emacs will take
+@code{push-button} rather than ``return'' or ``enter''. Emacs will take
you directly to the function definition.
@ignore
If you move point over the file name and press
the @key{RET} key, which in this case means @code{help-follow} rather
-than `return' or `enter', Emacs will take you directly to the function
+than ``return'' or ``enter'', Emacs will take you directly to the function
definition.
@end ignore
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
frequently use @code{find-tag} to navigate your way around source code;
and you will create your own @file{TAGS} tables.
-@cindex Library, as term for `file'
+@cindex Library, as term for ``file''
Incidentally, the files that contain Lisp code are conventionally
called @dfn{libraries}. The metaphor is derived from that of a
specialized library, such as a law library or an engineering library,
highest numbered place in the buffer that it can. However, in this
version, @code{push-mark} has two additional arguments. The second
argument to @code{push-mark} is @code{nil}. This tells the function
-it @emph{should} display a message that says `Mark set' when it pushes
+it @emph{should} display a message that says ``Mark set'' when it pushes
the mark. The third argument is @code{t}. This tells
@code{push-mark} to activate the mark when Transient Mark mode is
turned on. Transient Mark mode highlights the currently active
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
The body of the @code{let} expression in @code{append-to-buffer}
consists of a @code{save-excursion} expression.
-The @code{save-excursion} function saves the locations of point and
-mark, and restores them to those positions after the expressions in the
+The @code{save-excursion} function saves the location of point, and restores it
+to that position after the expressions in the
body of the @code{save-excursion} complete execution. In addition,
@code{save-excursion} keeps track of the original buffer, and
restores it. This is how @code{save-excursion} is used in
@key{META} key).
@item save-excursion
-Save the location of point and mark and restore their values after the
+Save the location of point and restore its value after the
arguments to @code{save-excursion} have been evaluated. Also, remember
the current buffer and return to it.
attention, so you don't know that that buffer is now called
@code{oldbuf}).
-Incidentally, this is what is meant by `replacement'. To replace text,
+Incidentally, this is what is meant by ``replacement''. To replace text,
Emacs erases the previous text and then inserts new text.
@need 1250
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
recorded in the variable @code{newmark}.
After the body of the outer @code{save-excursion} is evaluated, point
-and mark are relocated to their original places.
+is relocated to its original place.
However, it is convenient to locate a mark at the end of the newly
inserted text and locate point at its beginning. The @code{newmark}
Emacs used numbers that are no bigger than eight million or so and in
the computation that followed, the programmer feared that Emacs might
try to use over-large numbers if the buffer were large. The term
-`overflow', mentioned in the comment, means numbers that are over
+``overflow'', mentioned in the comment, means numbers that are over
large. More recent versions of Emacs use larger numbers, but this
code has not been touched, if only because people now look at buffers
that are far, far larger than ever before.
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
@code{save-restriction} special form.
The call to @code{widen} is followed by @code{save-excursion}, which
-saves the location of the cursor (i.e., of point) and of the mark, and
-restores them after the code in the body of the @code{save-excursion}
+saves the location of the cursor (i.e., of point), and
+restores it after the code in the body of the @code{save-excursion}
uses the @code{beginning-of-line} function to move point.
(Note that the @code{(widen)} expression comes between the
current line.
After @code{count-lines} has done its job, and the message has been
-printed in the echo area, the @code{save-excursion} restores point and
-mark to their original positions; and @code{save-restriction} restores
+printed in the echo area, the @code{save-excursion} restores point to
+its original position; and @code{save-restriction} restores
the original narrowing, if any.
@node narrow Exercise
@end ifnottex
The name of the @code{cons} function is not unreasonable: it is an
-abbreviation of the word `construct'. The origins of the names for
+abbreviation of the word ``construct''. The origins of the names for
@code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
-is an acronym from the phrase `Contents of the Address part of the
-Register'; and @code{cdr} (pronounced `could-er') is an acronym from
-the phrase `Contents of the Decrement part of the Register'. These
+is an acronym from the phrase ``Contents of the Address part of the
+Register''; and @code{cdr} (pronounced ``could-er'') is an acronym from
+the phrase ``Contents of the Decrement part of the Register''. These
phrases refer to specific pieces of hardware on the very early
computer on which the original Lisp was developed. Besides being
obsolete, the phrases have been completely irrelevant for more than 25
@code{car} does not remove the first item from the list; it only reports
what it is. After @code{car} has been applied to a list, the list is
still the same as it was. In the jargon, @code{car} is
-`non-destructive'. This feature turns out to be important.
+``non-destructive''. This feature turns out to be important.
The @sc{cdr} of a list is the rest of the list, that is, the
@code{cdr} function returns the part of the list that follows the
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.
series of @code{cons} expressions that build up a list of flowers. If
you are reading this in Info in GNU Emacs, you can evaluate each of
the expressions in the usual way; the value is printed in this text
-after @samp{@result{}}, which you may read as `evaluates to'.
+after @samp{@result{}}, which you may read as ``evaluates to''.
@smallexample
@group
This is written with a special notation, @samp{#<subr},
that indicates that the function @code{length} is one of the primitive
functions written in C rather than in Emacs Lisp. (@samp{subr} is an
- abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a
+ abbreviation for ``subroutine''.) @xref{What Is a Function, , What Is a
Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
about subroutines.
@end ignore
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
+(The use of the word ``kill'' in Emacs for processes which specifically
@emph{do not} destroy the values of the entities is an unfortunate
-historical accident. A much more appropriate word would be `clip' since
+historical accident. A much more appropriate word would be ``clip'' since
that is what the kill commands do; they clip text out of a buffer and
put it into storage from which it can be brought back. I have often
-been tempted to replace globally all occurrences of `kill' in the Emacs
-sources with `clip' and all occurrences of `killed' with `clipped'.)
+been tempted to replace globally all occurrences of ``kill'' in the Emacs
+sources with ``clip'' and all occurrences of ``killed'' with ``clipped''.)
@menu
* Storing Text:: Text is stored in a list.
@need 1200
@noindent
The function @code{cons} can be used to create a new list from a piece
-of text (an `atom', to use the jargon) and an existing list, like
+of text (an ``atom'', to use the jargon) and an existing list, like
this:
@smallexample
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.
@end smallexample
The documentation is thorough. You do need to know the jargon meaning
-of the word `kill'.
+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:
;; @bullet{} Since order matters, pass point first.
(interactive (list (point) (mark)))
;; @bullet{} And tell us if we cannot cut the text.
- ;; `unless' is an `if' without a then-part.
+ ;; 'unless' is an 'if' without a then-part.
(unless (and beg end)
(error "The mark is not set now, so there is no region"))
@end group
@group
- ;; @bullet{} `condition-case' takes three arguments.
+ ;; @bullet{} 'condition-case' takes three arguments.
;; If the first argument is nil, as it is here,
;; information about the error signal is not
;; stored for use by another function.
@end group
@group
- ;; @bullet{} The second argument to `condition-case' tells the
+ ;; @bullet{} The second argument to 'condition-case' tells the
;; Lisp interpreter what to do when all goes well.
@end group
@group
- ;; It starts with a `let' function that extracts the string
+ ;; It starts with a 'let' function that extracts the string
;; and tests whether it exists. If so (that is what the
- ;; `when' checks), it calls an `if' function that determines
+ ;; 'when' checks), it calls an 'if' function that determines
;; whether the previous command was another call to
- ;; `kill-region'; if it was, then the new text is appended to
+ ;; 'kill-region'; if it was, then the new text is appended to
;; the previous text; if not, then a different function,
- ;; `kill-new', is called.
+ ;; 'kill-new', is called.
@end group
@group
- ;; The `kill-append' function concatenates the new string and
- ;; the old. The `kill-new' function inserts text into a new
+ ;; The 'kill-append' function concatenates the new string and
+ ;; the old. The 'kill-new' function inserts text into a new
;; item in the kill ring.
@end group
@group
- ;; `when' is an `if' without an else-part. The second `when'
+ ;; 'when' is an 'if' without an else-part. The second 'when'
;; again checks whether the current string exists; in
;; addition, it checks whether the previous command was
- ;; another call to `kill-region'. If one or the other
+ ;; another call to 'kill-region'. If one or the other
;; condition is true, then it sets the current command to
- ;; be `kill-region'.
+ ;; be 'kill-region'.
@end group
@group
(let ((string (filter-buffer-substring beg end t)))
(if (eq last-command 'kill-region)
@end group
@group
- ;; @minus{} `yank-handler' is an optional argument to
- ;; `kill-region' that tells the `kill-append' and
- ;; `kill-new' functions how deal with properties
- ;; added to the text, such as `bold' or `italics'.
+ ;; @minus{} 'yank-handler' is an optional argument to
+ ;; 'kill-region' that tells the 'kill-append' and
+ ;; 'kill-new' functions how deal with properties
+ ;; added to the text, such as 'bold' or 'italics'.
(kill-append string (< end beg) yank-handler)
(kill-new string nil yank-handler)))
(when (or string (eq last-command 'kill-region))
@end group
@group
- ;; @bullet{} The third argument to `condition-case' tells the interpreter
+ ;; @bullet{} The third argument to 'condition-case' tells the interpreter
;; what to do with an error.
@end group
@group
@end group
@group
- ;; 1. `condition-case' takes three arguments.
+ ;; 1. 'condition-case' takes three arguments.
;; If the first argument is nil, as it is here,
;; information about the error signal is not
;; stored for use by another function.
@end group
@group
- ;; 2. The second argument to `condition-case'
+ ;; 2. The second argument to 'condition-case'
;; tells the Lisp interpreter what to do when all goes well.
@end group
@group
- ;; The `delete-and-extract-region' function usually does the
+ ;; The 'delete-and-extract-region' function usually does the
;; work. If the beginning and ending of the region are both
- ;; the same, then the variable `string' will be empty, or nil
+ ;; the same, then the variable 'string' will be empty, or nil
(let ((string (delete-and-extract-region beg end)))
@end group
@group
- ;; `when' is an `if' clause that cannot take an `else-part'.
- ;; Emacs normally sets the value of `last-command' to the
+ ;; 'when' is an 'if' clause that cannot take an 'else-part'.
+ ;; Emacs normally sets the value of 'last-command' to the
;; previous command.
@end group
@group
- ;; `kill-append' concatenates the new string and the old.
- ;; `kill-new' inserts text into a new item in the kill ring.
+ ;; 'kill-append' concatenates the new string and the old.
+ ;; 'kill-new' inserts text into a new item in the kill ring.
(when string
(if (eq last-command 'kill-region)
;; if true, prepend string
@end group
@group
- ;; 3. The third argument to `condition-case' tells the interpreter
+ ;; 3. The third argument to 'condition-case' tells the interpreter
;; what to do with an error.
@end group
@group
generating the error signal will define one or more error condition
names.
-An error handler is the third argument to @code{condition case}.
+An error handler is the third argument to @code{condition-case}.
An error handler has two parts, a @var{condition-name} and a
@var{body}. If the @var{condition-name} part of an error handler
matches a condition name generated by an error, then the @var{body}
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}).
@end ignore
@code{menu-bar-update-yank-menu} is one of the functions that make it
-possible to use the `Select and Paste' menu in the Edit item of a menu
+possible to use the ``Select and Paste'' menu in the Edit item of a menu
bar; using a mouse, you can look at the various pieces of text you
have saved and select one piece to paste.
bringing back text that has been cut out of the buffer---the yank
commands. However, before discussing the yank commands, it is better
to learn how lists are implemented in a computer. This will make
-clear such mysteries as the use of the term `pointer'. But before
+clear such mysteries as the use of the term ``pointer''. But before
that, we will digress into C.
@ignore
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
two integers that mark the beginning and end of the region to be
deleted@footnote{More precisely, and requiring more expert knowledge
-to understand, the two integers are of type `Lisp_Object', which can
+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:
its remaining arguments to its first argument.
@item nthcdr
-Return the result of taking @sc{cdr} `n' times on a list.
+Return the result of taking @sc{cdr} @var{n} times on a list.
@iftex
The
@tex
@end tex
@code{cdr}.
@end iftex
-The `rest of the rest', as it were.
+The ``rest of the rest'', as it were.
@need 1250
For example:
If a symbol is set to the @sc{cdr} of a list, the list itself is not
changed; the symbol simply has an address further down the list. (In
-the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus,
+the jargon, @sc{car} and @sc{cdr} are ``non-destructive''.) Thus,
evaluation of the following expression
@smallexample
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).
element with the third, fourth, or fifth element, and so on. When the
last element in the kill ring is reached, it is replaced by the first
element and the cycle is repeated. (Thus the kill ring is called a
-`ring' rather than just a `list'. However, the actual data structure
+``ring'' rather than just a ``list''. However, the actual data structure
that holds the text is a list.
@xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
list is handled as a ring.)
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))))))
different arguments. The code runs exactly the same because it has
the same name. However, even though the program has the same name, it
is not the same entity. It is different. In the jargon, it is a
-different `instance'.
+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
+We often say that a recursive function ``calls itself''. What we mean
is that the instructions in a recursive function cause the Lisp
interpreter to run a different function that has the same name and
does the same job as the first, but with different arguments.
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.
-Note that although we say that the function `calls itself', what we
+Note that although we say that the function ``calls itself'', what we
mean is that the Lisp interpreter assembles and instructs a new
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
off the calculation for @code{(triangle-recursively 6)} to a second
instance of the program, to a second robot. This second individual is
completely different from the first one; it is, in the jargon, a
-`different instantiation'. Or, put another way, it is a different
+``different instantiation''. Or, put another way, it is a different
robot. It is the same model as the first; it calculates triangle
numbers recursively; but it has a different serial number.
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.}
+``recursive'' has different meanings in the two contexts.}
Let's see what happens when we have a triangle that has one row. (This
triangle will have one pebble in it!)
@uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
@end ifhtml
@iftex
-``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
+``Indicating Definitions, Commands, etc.''@: in @cite{Texinfo, The GNU
Documentation Format}.
@end iftex
@end itemize
Regular expression searches are used extensively in GNU Emacs. The
two functions, @code{forward-sentence} and @code{forward-paragraph},
illustrate these searches well. They use regular expressions to find
-where to move point. The phrase `regular expression' is often written
-as `regexp'.
+where to move point. The phrase ``regular expression'' is often written
+as ``regexp''.
Regular expression searches are described in @ref{Regexp Search, ,
Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
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
The GNU Emacs sources come with a @file{Makefile} that contains a
sophisticated @code{etags} command that creates, collects, and merges
tags tables from all over the Emacs sources and puts the information
-into one @file{TAGS} file in the @file{src/} directory. (The
+into one @file{TAGS} file in the @file{src/} directory. (The
@file{src/} directory is below the top level of your Emacs directory.)
@need 1250
@smallexample
@group
(let* ((foo 7)
- (bar (* 3 foo)))
+ (bar (* 3 foo)))
(message "`bar' is %d." bar))
- @result{} `bar' is 21.
+ @result{} ‘bar’ is 21.
@end group
@end smallexample
or more blank lines in sequence.
@item
-Write a function to search for duplicated words, such as `the the'.
+Write a function to search for duplicated words, such as ``the the''.
@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
Manual}, for information on how to write a regexp (a regular
expression) to match a string that is composed of two identical
We could use @code{(forward-word 1)} as the expression for moving point
forward word by word, but it is easier to see what Emacs identifies as a
-`word' if we use a regular expression search.
+``word'' if we use a regular expression search.
A regular expression search that finds the pattern for which it is
searching leaves point after the last character matched. This means
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.
When we first start thinking about how to count the words in a
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
+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
@noindent
This regular expression is a pattern defining one or more word
constituent characters possibly followed by one or more characters
-that are not word constituents. What is meant by `word constituent
-characters' brings us to the issue of syntax, which is worth a section
+that are not word constituents. What is meant by ``word constituent
+characters'' brings us to the issue of syntax, which is worth a section
of its own.
@node Syntax
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
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.
@end group
@group
(cond
- ;; check to see whether filename ends in `.el'
+ ;; check to see whether filename ends in '.el'
;; and if so, append its name to a list.
((equal ".el" (substring (car (car current-directory-list)) -3))
(setq el-files-list
(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.
What we want to look for is some command that prints or inserts
columns. Very likely, the name of the function will contain either
-the word `print' or the word `insert' or the word `column'.
+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
@end smallexample
@noindent
-`Mode help', as I call this, is very helpful. Usually, it tells you
+``Mode help'', as I call this, is very helpful. Usually, it tells you
all you need to know.
Of course, you don't need to include comments like these in your
@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
@group
;;; Mail mode
-; To enter mail mode, type `C-x m'
+; To enter mail mode, type 'C-x m'
; To enter RMAIL (for reading mail),
-; type `M-x rmail'
+; type 'M-x rmail'
(setq mail-aliases t)
@end group
@end 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
values for the variable.
@ifinfo
-@xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}.
+@xref{Just Spaces, , Tabs vs.@: Spaces, emacs, The GNU Emacs Manual}.
@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
Manual}.
@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
-;;; Keybinding for `occur'
+;;; Keybinding for 'occur'
; I use occur a lot, so let's bind it to a key:
(global-set-key "\C-co" 'occur)
@end group
@smallexample
@group
-;;; Unbind `C-x f'
+;;; Unbind 'C-x f'
(global-unset-key "\C-xf")
@end group
@end smallexample
@smallexample
@group
-;;; Rebind `C-x C-b' for `buffer-menu'
+;;; Rebind 'C-x C-b' for 'buffer-menu'
(global-set-key "\C-x\C-b" 'buffer-menu)
@end group
@end smallexample
@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
@end smallexample
The name of the function, @code{load-library}, comes from the use of
-`library' as a conventional synonym for `file'. The source for the
+``library'' as a conventional synonym for ``file''. The source for the
@code{load-library} command is in the @file{files.el} library.
Another interactive command that does a slightly different job is
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.)
@group
(when (>= emacs-major-version 21)
(blink-cursor-mode 0)
- ;; Insert newline when you press `C-n' (next-line)
+ ;; Insert newline when you press 'C-n' (next-line)
;; at the end of the buffer
(setq next-line-add-newlines t)
@end group
@smallexample
@group
; Cursor shapes are defined in
-; `/usr/include/X11/cursorfont.h';
-; for example, the `target' cursor is number 128;
-; the `top_left_arrow' cursor is number 132.
+; '/usr/include/X11/cursorfont.h';
+; for example, the 'target' cursor is number 128;
+; the 'top_left_arrow' cursor is number 132.
@end group
@group
@smallexample
@group
-;; Translate `C-h' to <DEL>.
+;; Translate 'C-h' to <DEL>.
; (keyboard-translate ?\C-h ?\C-?)
-;; Translate <DEL> to `C-h'.
+;; Translate <DEL> to 'C-h'.
(keyboard-translate ?\C-? ?\C-h)
@end group
@end smallexample
or start GNU Emacs with the command @code{emacs -nbc}.
@need 1250
-@item When using `grep'@*
+@item When using @command{grep}@*
@samp{-i}@w{ } Ignore case distinctions@*
@samp{-n}@w{ } Prefix each line of output with line number@*
@samp{-H}@w{ } Print the filename for each match.@*
@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
@smallexample
@group
-# Bind the key labeled `Caps Lock' to `Control'
+# Bind the key labeled 'Caps Lock' to 'Control'
# (Such a broken user interface suggests that keyboard manufacturers
# think that computers are typewriters from 1885.)
The @code{#(} begins the list.
The @samp{"%12b"} displays the current buffer name, using the
-@code{buffer-name} function with which we are familiar; the `12'
+@code{buffer-name} function with which we are familiar; the @samp{12}
specifies the maximum number of characters that will be displayed.
When a name has fewer characters, whitespace is added to fill out to
this number. (Buffer names can and often should be longer than 12
@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.
@end smallexample
@samp{%[} and @samp{%]} cause a pair of square brackets
-to appear for each recursive editing level. @samp{%n} says `Narrow'
+to appear for each recursive editing level. @samp{%n} says ``Narrow''
when narrowing is in effect. @samp{%P} tells you the percentage of
-the buffer that is above the bottom of the window, or `Top', `Bottom',
-or `All'. (A lower case @samp{p} tell you the percentage above the
+the buffer that is above the bottom of the window, or ``Top'', ``Bottom'',
+or ``All''. (A lower case @samp{p} tell you the percentage above the
@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
You might try searching just for duplicated word-constituent
characters but that does not work since the pattern detects doubles
-such as the two occurrences of `th' in `with the'.
+such as the two occurrences of ``th'' in ``with the''.
Another possible regexp searches for word-constituent characters
followed by non-word-constituent characters, reduplicated. Here,
@end group
@group
-;; Bind `the-the' to C-c \
+;; Bind 'the-the' to C-c \
(global-set-key "\C-c\\" 'the-the)
@end group
@end smallexample
@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}.)
@ifnottex
@node Digression concerning error
-@unnumberedsubsubsec Digression about the word `error'
+@unnumberedsubsubsec Digression about the word ``error''
@end ifnottex
In my opinion, it is slightly misleading, at least to humans, to use
-the term `error' as the name of the @code{error} function. A better
-term would be `cancel'. Strictly speaking, of course, you cannot
+the term ``error'' as the name of the @code{error} function. A better
+term would be ``cancel''. Strictly speaking, of course, you cannot
point to, much less rotate a pointer to a list that has no length, so
-from the point of view of the computer, the word `error' is correct.
+from the point of view of the computer, the word ``error'' is correct.
But a human expects to attempt this sort of thing, if only to find out
whether the kill ring is full or empty. This is an act of
exploration.
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
-`cancel' would have a clearer connotation.
+takes the same steps as it does when there is an error, a term such as
+``cancel'' would have a clearer connotation.
@ifnottex
@node Determining the Element
"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}.
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
-(A question: is the `2' on the bottom of the vertical axis a bug or a
-feature? If you think it is a bug, and should be a `1' instead, (or
-even a `0'), you can modify the sources.)
+(A question: is the @samp{2} on the bottom of the vertical axis a bug or a
+feature? If you think it is a bug, and should be a @samp{1} instead, (or
+even a @samp{0}), you can modify the sources.)
@node Graphing words in defuns
@appendixsubsec Graphing Numbers of Words and Symbols
@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
a sequence.
The @samp{map} part of the name comes from the mathematical phrase,
-`mapping over a domain', meaning to apply a function to each of the
+``mapping over a domain'', meaning to apply a function to each of the
elements in a domain. The mathematical phrase is based on the
metaphor of a surveyor walking, one step at a time, over an area he is
mapping. And @samp{car}, of course, comes from the Lisp notion of the
@cindex Bug, most insidious type
@cindex Insidious type of bug
-I said `almost ready to print'! Of course, there is a bug in the
+I said ``almost ready to print''! Of course, there is a bug in the
@code{print-graph} function @dots{} It has a @code{vertical-step}
option, but not a @code{horizontal-step} option. The
@code{top-of-range} scale goes from 10 to 300 by tens. But the
@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
;; Value of height and full-Y-label-width
-;; are passed by `print-graph'.
+;; are passed by 'print-graph'.
(let ((start (point)))
(insert-rectangle
(Y-axis-column height full-Y-label-width vertical-step))
@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
see the need to write a free manual. They do not see that the free
operating system has a gap that needs filling.
-Why do users think that proprietary manuals are good enough? Some have
+Why do users think that proprietary manuals are good enough? Some have
not considered the issue. I hope this article will do something to
change that.