diff options
Diffstat (limited to 'doc/lispintro/emacs-lisp-intro.texi')
| -rw-r--r-- | doc/lispintro/emacs-lisp-intro.texi | 807 |
1 files changed, 382 insertions, 425 deletions
diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index d9493879b1d..df8fa2f8e79 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -1,8 +1,6 @@ \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 @include docstyle.texi @syncodeindex vr cp @@ -63,10 +61,6 @@ \global\hbadness=6666 % don't worry about not-too-underfull boxes @end tex -@c These refer to the printed book sold by the FSF. -@set edition-number 3.10 -@set update-date 28 October 2009 - @c For next or subsequent edition: @c create function using with-output-to-temp-buffer @c create a major mode, with keymaps @@ -102,18 +96,26 @@ * Emacs Lisp Intro: (eintr). A simple introduction to Emacs Lisp programming. @end direntry +@c When printing, define edition-number to be the printed edition +@c number, titlepage-edition-number to be the spelled out edition +@c number suitable for the title page, and update-date to be the date, +@c in the preferred style for these. E.g., run the shell command: +@c texi2any -D 'edition-number 3.11' \ +@c -D 'titlepage-edition-number Revised Third Edition' \ +@c -D 'update-date 31 March 2020' +@c This relates mainly to the published book sold by the FSF. + @copying -This is an @cite{Introduction to Programming in Emacs Lisp}, for +This is @cite{An Introduction to Programming in Emacs Lisp}, for people who are not programmers. @sp 1 -@iftex +@ifset edition-number Edition @value{edition-number}, @value{update-date} -@end iftex -@ifnottex +@end ifset +@sp 1 Distributed with Emacs version @value{EMACSVER}. -@end ifnottex @sp 1 -Copyright @copyright{} 1990--1995, 1997, 2001--2017 Free Software +Copyright @copyright{} 1990--1995, 1997, 2001--2022 Free Software Foundation, Inc. @sp 1 @@ -173,7 +175,9 @@ supports it in developing GNU and promoting software freedom.'' @sp 2 @center @titlefont{Programming in Emacs Lisp} @sp 2 -@center Revised Third Edition +@ifset titlepage-edition-number +@center @value{titlepage-edition-number} +@end ifset @sp 4 @center by Robert J. Chassell @@ -198,6 +202,31 @@ supports it in developing GNU and promoting software freedom.'' @end ifset @end ifnothtml +@c If you think this manual is too large for an introduction, please +@c consider this email exchange: +@c +@c >> The intro is almost 300 pages in full. I had expected 60 pages. +@c > +@c > This is an important point in its own right. Could you +@c > write a simplified introduction that is only 50 pages or so? +@c > That would be helpful to many potential users, I'd think. +@c +@c > The problem with the introduction is that it was written when +@c > programming was only starting to be a skill "normal" people could +@c > have access to. So the text is extremely verbose and is +@c > sometimes hard to follow because of that. The gist of the +@c > document could be summarized in 50 pages. +@c +@c This book is intentionally addressed to people who don't know how to +@c program. That is its purpose. We recommend people start learning to +@c program using this book. +@c +@c If you DO know how to program in some other language, you can probably +@c learn Emacs Lisp starting with the Emacs Lisp Reference Manual. +@c +@c Richard Stallman <rms@gnu.org>, +@c https://lists.gnu.org/r/emacs-devel/2018-05/msg00374.html + @shortcontents @contents @@ -207,7 +236,7 @@ supports it in developing GNU and promoting software freedom.'' @ifset WWW_GNU_ORG @html -<p>The homepage for GNU Emacs is at +<p>The GNU Emacs website is at <a href="/software/emacs/">https://www.gnu.org/software/emacs/</a>.<br> To view this manual in other formats, click <a href="/software/emacs/manual/eintr.html">here</a>. @@ -220,6 +249,10 @@ This master menu first lists each chapter and index; then it lists every node in every chapter. @end ifnottex +@c Uncomment the 3 lines below, starting with @iftex, if you want the +@c pages of Preface to be numbered in roman numerals. Use -9 instead +@c of -11 for smallbook format. + @c >>>> Set pageno appropriately <<<< @c The first page of the Preface is a roman numeral; it is the first @@ -455,7 +488,7 @@ Narrowing and Widening @code{car}, @code{cdr}, @code{cons}: Fundamental Functions -* Strange Names:: An historical aside: why the strange names? +* Strange Names:: A historical aside: why the strange names? * car & cdr:: Functions for extracting part of a list. * cons:: Constructing a list. * nthcdr:: Calling @code{cdr} repeatedly. @@ -653,7 +686,7 @@ Your @file{.emacs} File * Text and Auto-fill:: Automatically wrap lines. * Mail Aliases:: Use abbreviations for email addresses. * Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. +* Key Bindings:: Create some personal key bindings. * Keymaps:: More about key binding. * Loading Files:: Load (i.e., evaluate) files automatically. * Autoload:: Make functions available. @@ -797,10 +830,10 @@ programming language, the examples and guided tours will give you an opportunity to get acquainted with Emacs as a Lisp programming environment. GNU Emacs supports programming and provides tools that you will want to become comfortable using, such as @kbd{M-.} (the key -which invokes the @code{find-tag} command). You will also learn about -buffers and other objects that are part of the environment. -Learning about these features of Emacs is like learning new routes -around your home town. +which invokes the @code{xref-find-definitions} command). You will +also learn about buffers and other objects that are part of the +environment. Learning about these features of Emacs is like learning +new routes around your home town. @ignore In addition, I have written several programs as extended examples. @@ -831,7 +864,7 @@ An expert programmer who reviewed this text said to me: @i{I prefer to learn from reference manuals. I ``dive into'' each paragraph, and ``come up for air'' between paragraphs.} -@i{When I get to the end of a paragraph, I assume that that subject is +@i{When I get to the end of a paragraph, I assume that subject is done, finished, that I know everything I need (with the possible exception of the case when the next paragraph starts talking about it in more detail). I expect that a well written reference manual @@ -863,8 +896,8 @@ 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. -This introduction to @cite{Programming in Emacs Lisp} has a companion -document, +This book, @cite{An Introduction to Programming in Emacs Lisp}, has a +companion document, @iftex @cite{The GNU Emacs Lisp Reference Manual}. @end iftex @@ -894,7 +927,7 @@ GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT in the 1960s. It is somewhat inspired by Common Lisp, which became a standard in the 1980s. However, Emacs Lisp is much simpler than Common Lisp. (The standard Emacs distribution contains an optional extensions -file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) +file, @file{cl-lib.el}, that adds many Common Lisp features to Emacs Lisp.) @node Note for Novices @unnumberedsec A Note for Novices @@ -914,17 +947,17 @@ the command in parentheses, like this: @kbd{M-C-\} @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your -@key{META} key, @key{CTRL} key and @key{\} key all at the same time. +@key{META} key, @key{CTRL} key and @kbd{\} key all at the same time. (On many modern keyboards the @key{META} key is labeled @key{ALT}.) Sometimes a combination like this is called a keychord, since it is similar to the way you play a chord on a piano. If your keyboard does not have a @key{META} key, the @key{ESC} key prefix is used in place of it. In this case, @kbd{M-C-\} means that you press and release your -@key{ESC} key and then type the @key{CTRL} key and the @key{\} key at +@key{ESC} key and then type the @key{CTRL} key and the @kbd{\} key at the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key along with the key that is labeled @key{ALT} and, at the same time, -press the @key{\} key. +press the @kbd{\} key. In addition to typing a lone keychord, you can prefix what you type with @kbd{C-u}, which is called the @dfn{universal argument}. The @@ -987,6 +1020,8 @@ bob@@gnu.org @c makes a link to something in the first 4 pages though?). @c E.g., note that the Emacs manual has a preface, but does not bother @c resetting the page numbers back to 1 after that. +@c Alternatively, uncomment the 3 lines above (search for ``pageno'') +@c to have the preface numbered in roman numerals. @iftex @headings off @evenheading @thispage @| @| @thischapter @@ -1006,7 +1041,14 @@ putting them between parentheses. The parentheses mark the boundaries 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 +about special forms now. +@ifnottex +@xref{Complications}. +@end ifnottex +@iftex +@xref{Lisp Interpreter}. +@end iftex +} Lists are the basis of Lisp. @menu @@ -1118,6 +1160,10 @@ computer. Often, people use the term @dfn{expression} indiscriminately. (Also, in many texts, the word @dfn{form} is used as a synonym for expression.) +@c This and the next paragraph say ``kinds of atom'', but that is not +@c a typo, just slightly ``old-fashioned wording which adds a fillip +@c of interest to it'', and ``is more elegant writing'', according to +@c RMS. Incidentally, the atoms that make up our universe were named such when they were thought to be indivisible; but it has been found that physical atoms are not indivisible. Parts can split off an atom or it can @@ -1264,11 +1310,13 @@ hand parenthesis of the following list and then type @kbd{C-x C-e}: @c use code for the number four, not samp. @noindent -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}: +You will see the number @code{4} appear in the echo area@footnote{ +Emacs shows integer values in decimal, in octal and in hex, and also +as a character, but let's ignore this convenience feature for now. +}. (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}: @smallexample '(this is a quoted list) @@ -1318,19 +1366,6 @@ C-e}: (this is an unquoted list) @end smallexample -@ignore -@noindent -What you see depends on which version of Emacs you are running. GNU -Emacs version 22 provides more information than version 20 and before. -First, the more recent result of generating an error; then the -earlier, version 20 result. - -@need 1250 -@noindent -In GNU Emacs version 22, a @file{*Backtrace*} window will open up and -you will see the following in it: -@end ignore - A @file{*Backtrace*} window will open up and you should see the following in it: @@ -1339,10 +1374,12 @@ following in it: ---------- Buffer: *Backtrace* ---------- Debugger entered--Lisp error: (void-function this) (this is an unquoted list) - eval((this is an unquoted list)) - eval-last-sexp-1(nil) + eval((this is an unquoted list) nil) + elisp--eval-last-sexp(nil) eval-last-sexp(nil) - call-interactively(eval-last-sexp) + funcall-interactively(eval-last-sexp nil) + call-interactively(eval-last-sexp nil nil) + command-execute(eval-last-sexp) ---------- Buffer: *Backtrace* ---------- @end group @end smallexample @@ -1716,7 +1753,7 @@ function definition, and vice versa. @unnumberedsubsec @code{fill-column}, an Example Variable @end ifnottex -@findex fill-column, @r{an example variable} +@findex fill-column@r{, an example variable} @cindex Example variable, @code{fill-column} @cindex Variable, example of, @code{fill-column} The variable @code{fill-column} illustrates a symbol with a value @@ -1776,10 +1813,12 @@ You will create a @file{*Backtrace*} buffer that says: ---------- Buffer: *Backtrace* ---------- Debugger entered--Lisp error: (void-function fill-column) (fill-column) - eval((fill-column)) - eval-last-sexp-1(nil) + eval((fill-column) nil) + elisp--eval-last-sexp(nil) eval-last-sexp(nil) - call-interactively(eval-last-sexp) + funcall-interactively(eval-last-sexp nil) + call-interactively(eval-last-sexp nil nil) + command-execute(eval-last-sexp) ---------- Buffer: *Backtrace* ---------- @end group @end smallexample @@ -1788,19 +1827,6 @@ Debugger entered--Lisp error: (void-function fill-column) (Remember, to quit the debugger and make the debugger window go away, type @kbd{q} in the @file{*Backtrace*} buffer.) -@ignore -@need 800 -In GNU Emacs 20 and before, you will produce an error message that says: - -@smallexample -Symbol's function definition is void:@: fill-column -@end smallexample - -@noindent -(The message will go away as soon as you move the cursor or type -another key.) -@end ignore - @node Void Variable @subsection Error Message for a Symbol Without a Value @cindex Symbol without value error @@ -1826,9 +1852,11 @@ says: ---------- Buffer: *Backtrace* ---------- Debugger entered--Lisp error: (void-variable +) eval(+) - eval-last-sexp-1(nil) + elisp--eval-last-sexp(nil) eval-last-sexp(nil) - call-interactively(eval-last-sexp) + funcall-interactively(eval-last-sexp nil) + call-interactively(eval-last-sexp nil nil) + command-execute(eval-last-sexp) ---------- Buffer: *Backtrace* ---------- @end group @end smallexample @@ -1855,18 +1883,6 @@ Since @code{+} does not have a value bound to it, just the function definition, the error message reported that the symbol's value as a variable was void. -@ignore -@need 800 -In GNU Emacs version 20 and before, your error message will say: - -@example -Symbol's value as variable is void:@: + -@end example - -@noindent -The meaning is the same as in GNU Emacs 22. -@end ignore - @node Arguments @section Arguments @cindex Arguments @@ -2004,7 +2020,6 @@ the arguments to the function @code{concat} are the strings @w{@code{"The "}} and @w{@code{" red foxes."}} and the list @code{(number-to-string (+ 2 fill-column))}. -@c For GNU Emacs 22, need number-to-string @smallexample (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") @end smallexample @@ -2095,10 +2110,12 @@ You will create and enter a @file{*Backtrace*} buffer that says: Debugger entered--Lisp error: (wrong-type-argument number-or-marker-p hello) +(2 hello) - eval((+ 2 (quote hello))) - eval-last-sexp-1(nil) + eval((+ 2 'hello) nil) + elisp--eval-last-sexp(t) eval-last-sexp(nil) - call-interactively(eval-last-sexp) + funcall-interactively(eval-print-last-sexp nil) + call-interactively(eval-print-last-sexp nil nil) + command-execute(eval-print-last-sexp) ---------- Buffer: *Backtrace* ---------- @end group @end smallexample @@ -2126,9 +2143,10 @@ number---the number of characters the location is from the beginning of the buffer.) In Emacs Lisp, @code{+} can be used to add the numeric value of marker positions as numbers. +@cindex @samp{predicate} defined 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 @dfn{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 @@ -2143,19 +2161,6 @@ addition had been passed the correct type of object, the value passed would have been a number, such as 37, rather than a symbol like @code{hello}. But then you would not have got the error message. -@ignore -@need 1250 -In GNU Emacs version 20 and before, the echo area displays an error -message that says: - -@smallexample -Wrong type argument:@: number-or-marker-p, hello -@end smallexample - -This says, in different words, the same as the top line of the -@file{*Backtrace*} buffer. -@end ignore - @node message @subsection The @code{message} Function @findex message @@ -2275,7 +2280,7 @@ area. @cindex @samp{bind} defined There are several ways by which a variable can be given a value. One of -the ways is to use either the function @code{set} or the function +the ways is to use either the function @code{set} or the special form @code{setq}. Another way is to use @code{let} (@pxref{let}). (The jargon for this process is to @dfn{bind} a variable to a value.) @@ -2681,8 +2686,8 @@ In the old days, when you lacked a @file{~/.emacs} file and started an Emacs session by typing the command @code{emacs} alone, without naming any files, Emacs started with the @file{*scratch*} buffer visible. Nowadays, you will see a splash screen. You can follow one of the -commands suggested on the splash screen, visit a file, or press the -spacebar to reach the @file{*scratch*} buffer. +commands suggested on the splash screen, visit a file, or press @kbd{q} +to quit the splash screen and reach the @file{*scratch*} buffer. If you switch to the @file{*scratch*} buffer, type @code{(buffer-name)}, position the cursor after it, and then type @@ -3350,7 +3355,7 @@ Both the examples just mentioned work identically to move point forward three sentences. (Since @code{multiply-by-seven} is not bound to a key, it could not be used as an example of key binding.) -(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command +(@xref{Key Bindings, , Some Key Bindings}, to learn how to bind a command to a key.) A @dfn{prefix argument} is passed to an interactive function by typing the @@ -3613,7 +3618,8 @@ 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 a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, scoping is dynamic, not lexical. +in Emacs Lisp, the default scoping is dynamic, not lexical. (The +non-default lexical binding is not discussed in this manual.) @code{let} can create more than one variable at once. Also, @code{let} gives each variable it creates an initial value, either a @@ -3778,12 +3784,11 @@ delimit them from the body of the @code{let}. @findex if @cindex Conditional with @code{if} -A third special form, in addition to @code{defun} and @code{let}, is the -conditional @code{if}. This form is used to instruct the computer to -make decisions. You can write function definitions without using -@code{if}, but it is used often enough, and is important enough, to be -included here. It is used, for example, in the code for the -function @code{beginning-of-buffer}. +Another special form is the conditional @code{if}. This form is used +to instruct the computer to make decisions. You can write function +definitions without using @code{if}, but it is used often enough, and +is important enough, to be 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 @@ -3839,7 +3844,7 @@ message @samp{5 is greater than 4!} will be printed. @noindent (The function @code{>} tests whether its first argument is greater than its second argument and returns true if it is.) -@findex > (greater than) +@findex > @r{(greater than)} Of course, in actual use, the test in an @code{if} expression will not be fixed for all time as it is by the expression @code{(> 5 4)}. @@ -3943,7 +3948,7 @@ looks like this: @smallexample @group (if (equal characteristic "fierce") - (message "It is a tiger!"))) + (message "It is a tiger!")) @end group @end smallexample @@ -4156,8 +4161,8 @@ On the other hand, this function returns @code{nil} if the test is false. @findex point @findex mark -The @code{save-excursion} function is the third and final special form -that we will discuss in this chapter. +The @code{save-excursion} function is the final special form 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, @@ -4198,7 +4203,7 @@ times. The part of the buffer between point and mark is called @dfn{the region}. Numerous commands work on the region, including -@code{center-region}, @code{count-lines-region}, @code{kill-region}, and +@code{center-region}, @code{count-words-region}, @code{kill-region}, and @code{print-region}. The @code{save-excursion} special form saves the location of point and @@ -4211,7 +4216,7 @@ evaluated. In Emacs, a function frequently moves point as part of its internal workings even though a user would not expect this. For example, -@code{count-lines-region} moves point. To prevent the user from being +@code{count-words-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 in the location expected by the user. The use of @@ -4463,7 +4468,7 @@ number; it will be printed as the character with that @sc{ascii} code. @item setq @itemx set -The @code{setq} function sets the value of its first argument to the +The @code{setq} special form sets the value of its first argument to the value of the second argument. The first argument is automatically quoted by @code{setq}. It does the same for succeeding pairs of arguments. Another function, @code{set}, takes only two arguments and @@ -4552,7 +4557,7 @@ buffers. Later, we will study other functions. @node Finding More @section Finding More Information -@findex describe-function, @r{introduced} +@findex describe-function@r{, introduced} @cindex Find function documentation In this walk-through, I will describe each new function as we come to it, sometimes in detail and sometimes briefly. If you are interested, @@ -4586,16 +4591,25 @@ file, you can use the @code{xref-find-definitions} function to jump to it. @code{xref-find-definitions} works with a wide variety of languages, not just Lisp, and C, and it works with non-programming text as well. For example, @code{xref-find-definitions} will jump to -the various nodes in the Texinfo source file of this document. +the various nodes in the Texinfo source file of this document +(provided that you've run the @command{etags} utility to record all +the nodes in the manuals that come with Emacs; @pxref{Create Tags +Table,,, emacs, The GNU Emacs Manual}). To use the @code{xref-find-definitions} command, type @kbd{M-.} (i.e., press the period key while holding down the @key{META} key, or else type the @key{ESC} key and then type the period key), and then, at the prompt, type in the name of the function whose source code you want to see, such as @code{mark-whole-buffer}, and then type -@key{RET}. Emacs will switch buffers and display the source code for -the function on your screen. To switch back to your current buffer, -type @kbd{C-x b @key{RET}}. (On some keyboards, the @key{META} key is +@key{RET}. (If the command doesn't prompt, invoke it with an +argument: @kbd{C-u M-.}; @pxref{Interactive Options}.) Emacs will +switch buffers and display the source code for the function on your +screen@footnote{ +If instead of showing the source code for a Lisp function, Emacs asks +you which tags table to visit, invoke @kbd{M-.} from a buffer whose +major mode is Emacs Lisp or Lisp Interaction. +}. To switch back to your current buffer, type @kbd{M-,} or +@kbd{C-x b @key{RET}}. (On some keyboards, the @key{META} key is labeled @key{ALT}.) @cindex Library, as term for ``file'' @@ -4879,8 +4893,6 @@ result of this, point is placed at the beginning of the buffer and mark 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 @@ -4915,8 +4927,9 @@ buffer to which the text will go, the window it comes from and goes to, and the region that will be copied. @need 1250 -Here is the complete text of the function: +Here is a possible implementation of the function: +@c GNU Emacs 22 @smallexample @group (defun append-to-buffer (buffer start end) @@ -4983,7 +4996,9 @@ name. (The function can handle either.) Since the @code{append-to-buffer} function will be used interactively, the function must have an @code{interactive} expression. (For a review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: +Function Interactive}.) + +The expression reads as follows: @smallexample @group @@ -5012,7 +5027,7 @@ for true. The first argument to @code{other-buffer}, the exception, is yet another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that +returned. The second argument is the symbol for true, @code{t}. That tells @code{other-buffer} that it may show visible buffers (except in this case, it will not show the current buffer, which makes sense). @@ -5048,33 +5063,6 @@ point and mark. That argument worked fine.) @node append-to-buffer body @subsection The Body of @code{append-to-buffer} -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - The body of the @code{append-to-buffer} function begins with @code{let}. As we have seen before (@pxref{let, , @code{let}}), the purpose of a @@ -5093,7 +5081,7 @@ whole by showing a template for @code{append-to-buffer} with the "@var{documentation}@dots{}" (interactive @dots{}) (let ((@var{variable} @var{value})) - @var{body}@dots{}) + @var{body}@dots{})) @end group @end smallexample @@ -5213,19 +5201,39 @@ of filling in the slots of a template: @need 1200 @noindent +@anchor{let* introduced} +@findex let* In this function, the body of the @code{save-excursion} contains only one expression, the @code{let*} expression. You know about a -@code{let} function. The @code{let*} function is different. It has a -@samp{*} in its name. It enables Emacs to set each variable in its -varlist in sequence, one after another. +@code{let} function. The @code{let*} function is different. It +enables Emacs to set each variable in its varlist in sequence, one +after another; such that variables in the latter part of the varlist +can make use of the values to which Emacs set variables earlier in the +varlist. -Its critical feature is that variables later in the varlist can make -use of the values to which Emacs set variables earlier in the varlist. -@xref{fwd-para let, , The @code{let*} expression}. +Looking at the @code{let*} expression in @code{append-to-buffer}: -We will skip functions like @code{let*} and focus on two: the -@code{set-buffer} function and the @code{insert-buffer-substring} -function. +@smallexample +@group +(let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + BODY...) +@end group +@end smallexample + +@noindent +we see that @code{append-to} is bound to the value returned by the +@w{@code{(get-buffer-create buffer)}}. On the next line, +@code{append-to} is used as an argument to +@code{get-buffer-window-list}; this would not be possible with the +@code{let} expression. Note that @code{point} is automatically bound +to @code{nil}, the same way as it would be done in the @code{let} +statement. + +Now let's focus on the functions @code{set-buffer} and +@code{insert-buffer-substring} in the body of the @code{let*} +expression. @need 1250 In the old days, the @code{set-buffer} expression was simply @@ -5243,32 +5251,13 @@ but now it is @end smallexample @noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore +This is because @code{append-to} was bound to @code{(get-buffer-create +buffer)} earlier on in the @code{let*} expression. The @code{append-to-buffer} function definition inserts text from the buffer in which you are currently to a named buffer. It happens that -@code{insert-buffer-substring} copies text from another buffer to the -current buffer, just the reverse---that is why the +@code{insert-buffer-substring} does just the reverse---it copies text +from another buffer to the current buffer---that is why the @code{append-to-buffer} definition starts out with a @code{let} that binds the local symbol @code{oldbuf} to the value returned by @code{current-buffer}. @@ -5332,7 +5321,7 @@ Here is a brief summary of the various functions discussed in this chapter. Print the documentation for a function or variable. Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. -@item find-tag +@item xref-find-definitions Find the file containing the source for a function or variable and switch buffers to it, positioning point at the beginning of the item. Conventionally bound to @kbd{M-.} (that's a period following the @@ -5360,6 +5349,12 @@ an argument and insert the region into the current buffer. @item mark-whole-buffer Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. +@item let* +Declare a list of variables and give them an initial value; then +evaluate the rest of the expressions in the body of @code{let*}. The +values of the variables can be used to bind ensuing variables in the +list. + @item set-buffer Switch the attention of Emacs to another buffer, but do not change the window being displayed. Used when the program rather than a human is @@ -5386,8 +5381,8 @@ Use @code{if} and @code{get-buffer} to write a function that prints a message telling you whether a buffer exists. @item -Using @code{find-tag}, find the source for the @code{copy-to-buffer} -function. +Using @code{xref-find-definitions}, find the source for the +@code{copy-to-buffer} function. @end itemize @node More Complex @@ -5564,7 +5559,7 @@ outline of the function: @node insert-buffer interactive @subsection The Interactive Expression in @code{insert-buffer} -@findex interactive, @r{example use of} +@findex interactive@r{, example use of} In @code{insert-buffer}, the argument to the @code{interactive} declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert @@ -5785,7 +5780,7 @@ written like this: @subsection The @code{let} Expression in @code{insert-buffer} After ensuring that the variable @code{buffer} refers to a buffer itself -and not just to the name of a buffer, the @code{insert-buffer function} +and not just to the name of a buffer, the @code{insert-buffer} function continues with a @code{let} expression. This specifies three local variables, @code{start}, @code{end}, and @code{newmark} and binds them to the initial value @code{nil}. These variables are used inside the @@ -5881,8 +5876,8 @@ find and use again and again. @node New insert-buffer @subsection New Body for @code{insert-buffer} -@findex insert-buffer, new version body -@findex new version body for insert-buffer +@findex insert-buffer@r{, new version body} +@cindex new version body for @code{insert-buffer} The body in the GNU Emacs 22 version is more confusing than the original. @@ -6600,9 +6595,9 @@ original text of the function: @end group @end smallexample -(In recent versions of GNU Emacs, the @code{what-line} function has +(In modern versions of GNU Emacs, the @code{what-line} function has been expanded to tell you your line number in a narrowed buffer as -well as your line number in a widened buffer. The recent version is +well as your line number in a widened buffer. The modern version is more complex than the version shown here. If you feel adventurous, you might want to look at it after figuring out how this version works. You will probably need to use @kbd{C-h f} @@ -6734,8 +6729,8 @@ Or can you write the function without them? @node car cdr & cons @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions -@findex car, @r{introduced} -@findex cdr, @r{introduced} +@findex car@r{, introduced} +@findex cdr@r{, introduced} In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental functions. The @code{cons} function is used to construct lists, and @@ -6746,7 +6741,7 @@ will see @code{cons} as well as two variants on @code{cdr}, namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) @menu -* Strange Names:: An historical aside: why the strange names? +* Strange Names:: A historical aside: why the strange names? * car & cdr:: Functions for extracting part of a list. * cons:: Constructing a list. * nthcdr:: Calling @code{cdr} repeatedly. @@ -6900,7 +6895,7 @@ Emacs Lisp Reference Manual}.) @node cons @section @code{cons} -@findex cons, @r{introduced} +@findex cons@r{, introduced} The @code{cons} function constructs lists; it is the inverse of @code{car} and @code{cdr}. For example, @code{cons} can be used to make @@ -7255,10 +7250,17 @@ works is to experiment. We will start with the @code{setcar} function. @need 1200 First, we can make a list and then set the value of a variable to the -list, using the @code{setq} function. Here is a list of animals: +list, using the @code{setq} special form. Because we intend to use +@code{setcar} to change the list, this @code{setq} should not use the +quoted form @code{'(antelope giraffe lion tiger)}, as that would yield +a list that is part of the program and bad things could happen if we +tried to change part of the program while running it. Generally +speaking an Emacs Lisp program's components should be constant (or +unchanged) while the program is running. So we instead construct an +animal list by using the @code{list} function, as follows: @smallexample -(setq animals '(antelope giraffe lion tiger)) +(setq animals (list 'antelope 'giraffe 'lion 'tiger)) @end smallexample @noindent @@ -7335,7 +7337,7 @@ To see how this works, set the value of the variable to a list of domesticated animals by evaluating the following expression: @smallexample -(setq domesticated-animals '(horse cow sheep goat)) +(setq domesticated-animals (list 'horse 'cow 'sheep 'goat)) @end smallexample @need 1200 @@ -7627,7 +7629,7 @@ The first part of the code looks like this: @end smallexample @noindent -@code{char-table-p} is an hitherto unseen function. It determines +@code{char-table-p} is a hitherto unseen function. It determines whether its argument is a character table. When it is, it sets the character passed to @code{zap-to-char} to one of them, if that character exists, or to the character itself. (This becomes important @@ -8715,7 +8717,7 @@ example-list @noindent Now, we can add a new element on to this list by evaluating the following expression: -@findex push, @r{example} +@findex push@r{, example} @smallexample (push "a third clause" example-list) @@ -8748,7 +8750,7 @@ keeps the kill ring from growing too long. It looks like this: The code checks whether the length of the kill ring is greater than the maximum permitted length. This is the value of -@code{kill-ring-max} (which is 60, by default). If the length of the +@code{kill-ring-max} (which is 120, by default). If the length of the kill ring is too long, then this code sets the last element of the kill ring to @code{nil}. It does this by using two functions, @code{nthcdr} and @code{setcdr}. @@ -8762,13 +8764,13 @@ element of the kill ring---this means that since the @sc{cdr} of the next to last element is the last element of the kill ring, it will set the last element of the kill ring. -@findex nthcdr, @r{example} +@findex nthcdr@r{, example} The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} It does this @var{N} times and returns the results. (@xref{nthcdr, , @code{nthcdr}}.) -@findex setcdr, @r{example} +@findex setcdr@r{, example} Thus, if we had a four element list that was supposed to be three elements long, we could set the @sc{cdr} of the next to last element to @code{nil}, and thereby shorten the list. (If you set the last @@ -8783,7 +8785,7 @@ and then find the value of @code{trees}: @smallexample @group -(setq trees '(maple oak pine birch)) +(setq trees (list 'maple 'oak 'pine 'birch)) @result{} (maple oak pine birch) @end group @@ -8957,26 +8959,24 @@ Lisp; it is written in C and is one of the primitives of the GNU Emacs system. Since it is very simple, I will digress briefly from Lisp and describe it here. -@c GNU Emacs 24 in src/editfns.c -@c the DEFUN for delete-and-extract-region - @need 1500 Like many of the other Emacs primitives, @code{delete-and-extract-region} is written as an instance of a C macro, a macro being a template for code. The complete macro looks like this: +@c This is a copy of editfns.c's DEFUN for delete-and-extract-region. @smallexample @group DEFUN ("delete-and-extract-region", Fdelete_and_extract_region, Sdelete_and_extract_region, 2, 2, 0, doc: /* Delete the text between START and END and return it. */) - (Lisp_Object start, Lisp_Object end) + (Lisp_Object start, Lisp_Object end) @{ validate_region (&start, &end); - if (XINT (start) == XINT (end)) + if (XFIXNUM (start) == XFIXNUM (end)) return empty_unibyte_string; - return del_range_1 (XINT (start), XINT (end), 1, 1); + return del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1); @} @end group @end smallexample @@ -9040,9 +9040,9 @@ consists of the following four lines: @smallexample @group validate_region (&start, &end); -if (XINT (start) == XINT (end)) +if (XFIXNUM (start) == XFIXNUM (end)) return empty_unibyte_string; -return del_range_1 (XINT (start), XINT (end), 1, 1); +return del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1); @end group @end smallexample @@ -9054,27 +9054,28 @@ then return an empty string. 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_1}. These are @w{@code{XINT (start)}} and -@w{@code{XINT (end)}}. +passed to @code{del_range_1}. These are @w{@code{XFIXNUM (start)}} and +@w{@code{XFIXNUM (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 @code{Lisp_Object}, which can -also be a C union instead of an integer type.}. +two opaque values that mark the beginning and end of the region to be +deleted. More precisely, and requiring more expert knowledge +to understand, the two values are of type @code{Lisp_Object}, which +might be a C pointer, a C integer, or a C @code{struct}; C code +ordinarily should not care how @code{Lisp_Object} is implemented. -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. +@code{Lisp_Object} 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 +@samp{XFIXNUM} is a C macro that extracts the relevant integer from the longer collection of bits; the type bits are discarded. @need 800 The command in @code{delete-and-extract-region} looks like this: @smallexample -del_range_1 (XINT (start), XINT (end), 1, 1); +del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1); @end smallexample @noindent @@ -9304,7 +9305,7 @@ For example: @smallexample @group -(setq triple '(1 2 3)) +(setq triple (list 1 2 3)) (setcar triple '37) @@ -9485,7 +9486,7 @@ part of which is the address of the next pair. The very last box points to the symbol @code{nil}, which marks the end of the list. @need 1200 -When a variable is set to a list with a function such as @code{setq}, +When a variable is set to a list with an operation such as @code{setq}, it stores the address of the first box in the variable. Thus, evaluation of the expression @@ -9992,7 +9993,7 @@ kill-ring kill-ring-yank-pointer | | | | | --> "yet more text" | | - | --> "a different piece of text + | --> "a different piece of text" | --> "some text" @end group @@ -10099,9 +10100,8 @@ resources; as it happens, methods that people find easy---that are 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 -@code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to -15 and 30 times their default value.}. +increase the value of @code{max-lisp-eval-depth}. In my @file{.emacs} +file, I set it to 30 times its default value.}. @menu * while:: Causing a stretch of code to repeat. @@ -10295,9 +10295,8 @@ loop with a list. @cindex @file{*scratch*} buffer The function requires several lines for its output. If you are -reading this in a recent instance of GNU Emacs, -@c GNU Emacs 21, GNU Emacs 22, or a later version, -you can evaluate the following expression inside of Info, as usual. +reading this in a recent instance of GNU Emacs, you can evaluate the +following expression inside of Info, as usual. If you are using an earlier version of Emacs, you need to copy the necessary expressions to your @file{*scratch*} buffer and evaluate @@ -10323,9 +10322,8 @@ echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which each @samp{^J} stands for a newline.) @need 1500 -In a recent instance of GNU Emacs, you can evaluate these expressions -directly in the Info buffer, and the echo area will grow to show the -results. +You can evaluate these expressions directly in the Info buffer, and +the echo area will grow to show the results. @smallexample @group @@ -11013,9 +11011,8 @@ The @code{dotimes} macro is similar to @code{dolist}, except that it loops a specific number of times. The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 -and so forth each time around the loop, and the value of the third -argument is returned. You need to provide the value of the second -argument, which is how many times the macro loops. +and so forth each time around the loop. You need to provide the value +of the second argument, which is how many times the macro loops. @need 1250 For example, the following binds the numbers from 0 up to, but not @@ -11027,17 +11024,18 @@ three numbers in all, starting with zero as the first number.) @smallexample @group (let (value) ; otherwise a value is a void variable - (dotimes (number 3 value) - (setq value (cons number value)))) + (dotimes (number 3) + (setq value (cons number value))) + value) @result{} (2 1 0) @end group @end smallexample @noindent -@code{dotimes} returns @code{value}, so the way to use -@code{dotimes} is to operate on some expression @var{number} number of -times and then return the result, either as a list or an atom. +The way to use @code{dotimes} is to operate on some expression +@var{number} number of times and then return the result, either as +a list or an atom. @need 1250 Here is an example of a @code{defun} that uses @code{dotimes} to add @@ -11048,8 +11046,9 @@ up the number of pebbles in a triangle. (defun triangle-using-dotimes (number-of-rows) "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)))))) + (dotimes (number number-of-rows) + (setq total (+ total (1+ number)))) + total)) (triangle-using-dotimes 4) @end group @@ -11799,7 +11798,7 @@ Uses recursion." @end group @end smallexample -What happens when we call this function with a argument of 7? +What happens when we call this function with an argument of 7? The first instance of the @code{triangle-recursively} function adds the number 7 to the value returned by a second instance of @@ -12856,25 +12855,12 @@ familiar part of this function. @node fwd-para let @unnumberedsubsec The @code{let*} expression -The next line of the @code{forward-paragraph} function begins a -@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 -set variables in the earlier part of the varlist. - -@ignore -( refappend save-excursion, , code save-excursion in code append-to-buffer .) -@end ignore - -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) - -In the @code{let*} expression in this function, Emacs binds a total of -seven variables: @code{opoint}, @code{fill-prefix-regexp}, -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and +The next line of the @code{forward-paragraph} function begins a +@code{let*} expression (@pxref{let* introduced,,@code{let*} +introduced}), in which Emacs binds a total of seven variables: +@code{opoint}, @code{fill-prefix-regexp}, @code{parstart}, +@code{parsep}, @code{sp-parstart}, @code{start}, and @code{found-start}. The variable @code{parsep} appears twice, first, to remove instances @@ -13254,7 +13240,7 @@ If you are reading this inside of GNU Emacs and you want to see the whole function, you can type @kbd{C-h f} (@code{describe-function}) and the name of the function. This gives you the function documentation and the name of the library containing the function's -source. Place point over the name of the library and press the RET +source. Place point over the name of the library and press the @key{RET} key; you will be taken directly to the source. (Be sure to install your sources! Without them, you are like a person who tries to drive a car with his eyes shut!) @@ -13455,10 +13441,9 @@ The template for an interactive function definition is, as always: What we need to do is fill in the slots. -The name of the function should be self-explanatory and similar to the -existing @code{count-lines-region} name. This makes the name easier +The name of the function should be self-explanatory and easy to remember. @code{count-words-region} is the obvious choice. Since -that name is now used for the standard Emacs command to count words, we +that name is used for the standard Emacs command to count words, we will name our implementation @code{@value{COUNT-WORDS}}. The function counts words within a region. This means that the @@ -13672,7 +13657,7 @@ syntax table determines which characters these are." @end ifinfo @need 1000 -If you wish, you can also install this keybinding by evaluating it: +If you wish, you can also install this key binding by evaluating it: @smallexample (global-set-key "\C-c=" '@value{COUNT-WORDS}) @@ -14624,7 +14609,7 @@ almost the same code as for the recursive version of @need 800 @noindent -Let's re-use @kbd{C-c =} as a convenient keybinding: +Let's re-use @kbd{C-c =} as a convenient key binding: @smallexample (global-set-key "\C-c=" 'count-words-defun) @@ -14632,7 +14617,9 @@ Let's re-use @kbd{C-c =} as a convenient keybinding: Now we can try out @code{count-words-defun}: install both @code{count-words-in-defun} and @code{count-words-defun}, and set the -keybinding, and then place the cursor within the following definition: +key binding. Then copy the following to an Emacs Lisp buffer (like, +for instance, @file{*scratch*}), place the cursor within the +definition, and use the @kbd{C-c =} command. @smallexample @group @@ -14728,10 +14715,11 @@ creating one if none already exists." @noindent (The most recent version of the @code{find-file} function definition -permits you to specify optional wildcards to visit multiple files; that -makes the definition more complex and we will not discuss it here, -since it is not relevant. You can see its source using either -@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).) +permits you to specify optional wildcards to visit multiple files; +that makes the definition more complex and we will not discuss it +here, since it is not relevant. You can see its source using either +@kbd{M-.} (@code{xref-find-definitions}) or @kbd{C-h f} +(@code{describe-function}).) @ignore In Emacs 22 @@ -14739,7 +14727,7 @@ In Emacs 22 "Edit file FILENAME. Switch to a buffer visiting file FILENAME, creating one if none already exists. -Interactively, the default if you just type RET is the current directory, +Interactively, the default if you just type @key{RET} is the current directory, but the visited file name is available through the minibuffer history: type M-n to pull it into the minibuffer. @@ -14766,7 +14754,7 @@ 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 @var{wildcards} argument, -too, as well as another to read a file literally and an other you +too, as well as another to read a file literally and another to suppress warning messages. These optional arguments are irrelevant.) However, the @code{find-file-noselect} function does not select the @@ -15143,16 +15131,16 @@ Emacs may produce different results.) @end group @group -(lengths-list-file "./lisp/makesum.el") - @result{} (85 181) +(lengths-list-file "./lisp/hex-util.el") + @result{} (82 71) @end group @group (recursive-lengths-list-many-files '("./lisp/macros.el" "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) + "./lisp/hex-util.el")) + @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 82 71) @end group @end smallexample @@ -15244,27 +15232,13 @@ Sorting the list returned by the @code{recursive-lengths-list-many-files} function is straightforward; it uses the @code{<} function: -@ignore -2006 Oct 29 -In GNU Emacs 22, eval -(progn - (cd "/usr/local/share/emacs/22.0.50/") - (sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - '<)) - -@end ignore - @smallexample @group (sort (recursive-lengths-list-many-files '("./lisp/macros.el" "./lisp/mailalias.el" - "./lisp/makesum.el")) + "./lisp/hex-util.el")) '<) @end group @end smallexample @@ -15274,7 +15248,7 @@ In GNU Emacs 22, eval which produces: @smallexample -(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) +(29 32 38 71 82 90 95 178 180 218 263 283 321 324 480) @end smallexample @noindent @@ -15322,7 +15296,7 @@ as a list that looks like this (but with more elements): @group ("./lisp/macros.el" "./lisp/mail/rmail.el" - "./lisp/makesum.el") + "./lisp/hex-util.el") @end group @end smallexample @@ -15354,7 +15328,10 @@ nil @group (20615 27034 579989 697000) (17905 55681 0 0) -(20615 26327 734791 805000) +(20615 26327 734791 805000)@footnote{If @code{current-time-list} is +@code{nil} the three timestamps are @code{(1351051674579989697 +. 1000000000)}, @code{(1173477761000000000 . 1000000000)}, and +@code{(1351050967734791805 . 1000000000)}, respectively.} 13188 "-rw-r--r--" @end group @@ -15540,7 +15517,7 @@ like this: (recursive-lengths-list-many-files (files-in-below-directory "/usr/local/src/emacs/lisp/")) '<) - (insert (format "%s" (current-time-string)))) + (insert (current-time-string))) @end ignore @node Counting function definitions @@ -15917,8 +15894,8 @@ a regular expression, including functions that are not interactive. 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''. -Therefore, we can simply type @kbd{M-x apropos RET -print\|insert\|column RET} and look at the result. On my system, this +Therefore, we can simply type @kbd{M-x apropos @key{RET} +print\|insert\|column @key{RET}} and look at the result. On my system, this 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 @@ -15971,7 +15948,7 @@ placing point somewhere in the buffer, typing @kbd{M-:}, typing the and then typing @key{RET}. This causes Emacs to evaluate the expression in the minibuffer, but to use as the value of point the position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the -keybinding for @code{eval-expression}. Also, @code{nil} does not +key binding for @code{eval-expression}. Also, @code{nil} does not appear in the @file{*scratch*} buffer since the expression is evaluated in the minibuffer.) @@ -16368,9 +16345,9 @@ Install @code{graph-symbol}, @code{graph-blank}, @iftex @ref{Readying a Graph, , Readying a Graph}, @end iftex -@ifinfo +@ifnottex @ref{Columns of a graph}, -@end ifinfo +@end ifnottex and @code{graph-body-print}. @need 800 @@ -16538,7 +16515,7 @@ expressions in Emacs Lisp you can change or extend Emacs. * Text and Auto-fill:: Automatically wrap lines. * Mail Aliases:: Use abbreviations for email addresses. * Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. +* Key Bindings:: Create some personal key bindings. * Keymaps:: More about key binding. * Loading Files:: Load (i.e., evaluate) files automatically. * Autoload:: Make functions available. @@ -16740,7 +16717,7 @@ It will look like this: ;; If you edit it by hand, you could mess it up, so be careful. ;; Your init file should contain only one such instance. ;; If there is more than one, they won't work right. - '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) + '(text-mode-hook '(turn-on-auto-fill text-mode-hook-identify))) @end group @end smallexample @@ -17018,8 +16995,8 @@ reminders. @smallexample @group -;;; Mail mode -; To enter mail mode, type 'C-x m' +;;; Message mode +; To enter message mode, type 'C-x m' ; To enter RMAIL (for reading mail), ; type 'M-x rmail' (setq mail-aliases t) @@ -17028,7 +17005,7 @@ reminders. @cindex Mail aliases @noindent -This @code{setq} command sets the value of the variable +This @code{setq} sets the value of the variable @code{mail-aliases} to @code{t}. Since @code{t} means true, the line says, in effect, ``Yes, use mail aliases.'' @@ -17066,8 +17043,8 @@ The following turns off Indent Tabs mode: @end smallexample Note that this line uses @code{setq-default} rather than the -@code{setq} command that we have seen before. The @code{setq-default} -command sets values only in buffers that do not have their own local +@code{setq} that we have seen before; @code{setq-default} +sets values only in buffers that do not have their own local values for the variable. @ifinfo @@ -17082,10 +17059,10 @@ Files'' in @cite{The GNU Emacs Manual}. @end iftex @need 1700 -@node Keybindings -@section Some Keybindings +@node Key Bindings +@section Some Key Bindings -Now for some personal keybindings: +Now for some personal key bindings: @smallexample @group @@ -17107,10 +17084,10 @@ This also shows how to set a key globally, for all modes. @cindex Key setting globally @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 +key binding. In a @file{.emacs} file, the keybinding is written as 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 +control key and the @kbd{c} key at the same time. The @code{w} means +to press the @kbd{w} key. The key binding 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 @@ -17124,26 +17101,26 @@ 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 are necessary parts of -keybinding that I tend to forget. Fortunately, I have come to +key binding 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 +As for the key binding 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 @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 +key binding for your own use without stomping on someone else's +key binding. 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. @need 1250 -Here is another keybinding, with a comment: +Here is another key binding, with a comment: @smallexample @group -;;; Keybinding for 'occur' +;;; Key binding for 'occur' ; I use occur a lot, so let's bind it to a key: (global-set-key "\C-co" 'occur) @end group @@ -17177,8 +17154,8 @@ file, as I intended, I accidentally set the width for filled text, almost always to a width I did not want. Since I hardly ever reset my default width, I simply unbound the key. -@findex list-buffers, @r{rebound} -@findex buffer-menu, @r{bound to key} +@findex list-buffers@r{, rebound} +@findex buffer-menu@r{, bound to key} @need 1250 The following rebinds an existing key: @@ -17203,8 +17180,8 @@ but moves point into that window. @cindex Rebinding keys Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the keybinding for a single -command in all parts of Emacs, you are specifying the keybinding in +When you use @code{global-set-key} to set the key binding for a single +command in all parts of Emacs, you are specifying the key binding in @code{current-global-map}. Specific modes, such as C mode or Text mode, have their own keymaps; @@ -17436,9 +17413,9 @@ Manual}, for more information. @findex line-to-top-of-window @cindex Simple extension in @file{.emacs} file -Here is a simple extension to Emacs that moves the line point is on to -the top of the window. I use this all the time, to make text easier -to read. +Here is a simple extension to Emacs that moves the line that point is +on to the top of the window. I use this all the time, to make text +easier to read. You can put the following code into a separate file and then load it from your @file{.emacs} file, or you can include it within your @@ -17452,19 +17429,18 @@ Here is the definition: ;;; Line to top of window; ;;; replace three keystroke sequence C-u 0 C-l (defun line-to-top-of-window () - "Move the line point is on to top of window." + "Move the line that point is on to top of window." (interactive) (recenter 0)) @end group @end smallexample @need 1250 -Now for the keybinding. +Now for the key binding. -Nowadays, function keys as well as mouse button events and -non-@sc{ascii} characters are written within square brackets, without -quotation marks. (In Emacs version 18 and before, you had to write -different function key bindings for each different make of terminal.) +Function keys as well as mouse button events and non-@sc{ascii} +characters are written within square brackets, without quotation +marks. I bind @code{line-to-top-of-window} to my @key{F6} function key like this: @@ -17479,18 +17455,18 @@ Your Init File, emacs, The GNU Emacs Manual}. @cindex Conditional 'twixt two versions of Emacs @cindex Version of Emacs, choosing @cindex Emacs version, choosing -If you run two versions of GNU Emacs, such as versions 22 and 23, and +If you run two versions of GNU Emacs, such as versions 27 and 28, and use one @file{.emacs} file, you can select which code to evaluate with the following conditional: @smallexample @group (cond - ((= 22 emacs-major-version) - ;; evaluate version 22 code + ((= 27 emacs-major-version) + ;; evaluate version 27 code ( @dots{} )) - ((= 23 emacs-major-version) - ;; evaluate version 23 code + ((= 28 emacs-major-version) + ;; evaluate version 28 code ( @dots{} ))) @end group @end smallexample @@ -17718,17 +17694,6 @@ or start GNU Emacs with the command @code{emacs -nbc}. (setq grep-command "grep -i -nH -e ") @end smallexample -@ignore -@c Evidently, no longer needed in GNU Emacs 22 - -item Automatically uncompress compressed files when visiting them - -smallexample -(load "uncompress") -end smallexample - -@end ignore - @item Find an existing buffer, even if it has a different name@* This avoids problems with symbolic links. @@ -17765,7 +17730,7 @@ Some systems bind keys unpleasantly. Sometimes, for example, the @key{CTRL} key appears in an awkward spot rather than at the far left of the home row. -Usually, when people fix these sorts of keybindings, they do not +Usually, when people fix these sorts of key bindings, they do not change their @file{~/.emacs} file. Instead, they bind the proper keys on their consoles with the @code{loadkeys} or @code{install-keymap} commands in their boot script and then include @code{xmodmap} commands @@ -17820,7 +17785,7 @@ xmodmap -e "keysym Alt_L = Meta_L Alt_L" Finally, a feature I really like: a modified mode line. When I work over a network, I forget which machine I am using. Also, -I tend to I lose track of where I am, and which line point is on. +I tend to lose track of where I am, and which line point is on. So I reset my mode line to look like this: @@ -17866,7 +17831,7 @@ My @file{.emacs} file has a section that looks like this: #(" %[(" 0 6 (help-echo "mouse-1: select window, mouse-2: delete others ...")) - (:eval (mode-line-mode-name)) + (:eval (format-time-string "%F")) mode-line-process minor-mode-alist #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) @@ -18034,8 +17999,7 @@ argument of 4: @end smallexample @noindent -In a recent GNU Emacs, you will create and enter a @file{*Backtrace*} -buffer that says: +This will create and enter a @file{*Backtrace*} buffer that says: @noindent @smallexample @@ -18051,10 +18015,11 @@ Debugger entered--Lisp error: (void-function 1=) triangle-bugged(4) @end group @group - eval((triangle-bugged 4)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) + eval((triangle-bugged 4) nil) + eval-expression((triangle-bugged 4) nil nil 127) + funcall-interactively(eval-expression (triangle-bugged 4) nil nil 127) + call-interactively(eval-expression nil nil) + command-execute(eval-expression) ---------- Buffer: *Backtrace* ---------- @end group @end smallexample @@ -18068,25 +18033,12 @@ 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. -@ignore -@need 800 -In GNU Emacs 20 and before, you will see: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -which has the same meaning as the @file{*Backtrace*} buffer line in -version 21. -@end ignore - However, suppose you are not quite certain what is going on? You can read the complete backtrace. -In this case, you need to run a recent GNU Emacs, which automatically -starts the debugger that puts you in the @file{*Backtrace*} buffer; or -else, you need to start the debugger manually as described below. +Emacs automatically starts the debugger that puts you in the +@file{*Backtrace*} buffer. You can also start the debugger manually +as described below. Read the @file{*Backtrace*} buffer from the bottom up; it tells you what Emacs did that led to the error. Emacs made an interactive call @@ -18126,14 +18078,8 @@ then run your test again. @section @code{debug-on-entry} @findex debug-on-entry -A recent GNU Emacs starts the debugger automatically when your -function has an error. - -@ignore -GNU Emacs version 20 and before did not; it simply -presented you with an error message. You had to start the debugger -manually. -@end ignore +Emacs starts the debugger automatically when your function has an +error. Incidentally, you can start the debugger manually for all versions of Emacs; the advantage is that the debugger runs even if you do not have @@ -18147,7 +18093,7 @@ You can enter the debugger when you call the function by calling Type: @smallexample -M-x debug-on-entry RET triangle-bugged RET +M-x debug-on-entry @key{RET} triangle-bugged @key{RET} @end smallexample @need 1250 @@ -18168,12 +18114,13 @@ function: ---------- Buffer: *Backtrace* ---------- Debugger entered--entering a function: * triangle-bugged(5) - eval((triangle-bugged 5)) + eval((triangle-bugged 5) nil) @end group @group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) + eval-expression((triangle-bugged 5) nil nil 127) + funcall-interactively(eval-expression (triangle-bugged 5) nil nil 127) + call-interactively(eval-expression nil nil) + command-execute(eval-expression) ---------- Buffer: *Backtrace* ---------- @end group @end smallexample @@ -18192,9 +18139,11 @@ Debugger entered--beginning evaluation of function call form: eval((triangle-bugged 5)) @end group @group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) + eval((triangle-bugged 5) nil) + eval-expression((triangle-bugged 5) nil nil 127) + funcall-interactively(eval-expression (triangle-bugged 5) nil nil 127) + call-interactively(eval-expression nil nil) + command-execute(eval-expression) ---------- Buffer: *Backtrace* ---------- @end group @end smallexample @@ -18219,12 +18168,13 @@ Debugger entered--beginning evaluation of function call form: * (let ((total 0)) (while (> number 0) (setq total ...) (setq number ...)) total) * triangle-bugged(5) - eval((triangle-bugged 5)) + eval((triangle-bugged 5) nil) @group @end group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) + eval-expression((triangle-bugged 5) nil nil 127) + funcall-interactively(eval-expression (triangle-bugged 5) nil nil 127) + call-interactively(eval-expression nil nil) + command-execute(eval-expression) ---------- Buffer: *Backtrace* ---------- @end group @end smallexample @@ -18255,7 +18205,7 @@ To cancel the effect of @code{debug-on-entry}, call @code{cancel-debug-on-entry} and the name of the function, like this: @smallexample -M-x cancel-debug-on-entry RET triangle-bugged RET +M-x cancel-debug-on-entry @key{RET} triangle-bugged @key{RET} @end smallexample @noindent @@ -18341,7 +18291,7 @@ this by positioning your cursor within or just after the definition and typing @smallexample -M-x edebug-defun RET +M-x edebug-defun @key{RET} @end smallexample @noindent @@ -18518,8 +18468,8 @@ introduction, it comes as a Texinfo source file, so you can read it on your computer and as a typeset, printed book.) Go to the other built-in help that is part of GNU Emacs: the built-in -documentation for all functions and variables, and @code{find-tag}, -the program that takes you to sources. +documentation for all functions and variables, and +@code{xref-find-definitions}, the program that takes you to sources. Here is an example of how I explore the sources. Because of its name, @file{simple.el} is the file I looked at first, a long time ago. As @@ -18552,10 +18502,10 @@ one of those long, but decipherable functions. You can look up In this instance, since the code is Lisp, the @file{*Help*} buffer contains the name of the library containing the function's source. -You can put point over the name of the library and press the RET key, +You can put point over the name of the library and press the @key{RET} key, which in this situation is bound to @code{help-follow}, and be taken directly to the source, in the same way as @kbd{M-.} -(@code{find-tag}). +(@code{xref-find-definitions}). The definition for @code{describe-function} illustrates how to customize the @code{interactive} expression without using the standard @@ -18563,13 +18513,14 @@ 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 -source as does @code{find-tag}, when properly set up.) +source as does @code{xref-find-definitions}, when properly set up.) -You can look at a function's source using @code{find-tag}, which is -bound to @kbd{M-.} Finally, you can find out what the Reference -Manual has to say by visiting the manual in Info, and typing @kbd{i} -(@code{Info-index}) and the name of the function, or by looking up the -function in the index to a printed copy of the manual. +You can look at a function's source using +@code{xref-find-definitions}, which is bound to @kbd{M-.} Finally, +you can find out what the Reference Manual has to say by visiting the +manual in Info, and typing @kbd{i} (@code{Info-index}) and the name of +the function, or by looking up the function in the index to a printed +copy of the manual. Similarly, you can find out what is meant by @code{insert-and-inherit}. @@ -19148,11 +19099,14 @@ Local variables can only be accessed within the @code{let} that defines them or the function that specifies them in an argument list (and within expressions called by them). -@ignore @c texi2dvi fails when the name of the section is within ifnottex ... +@ifnottex (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and +@end ifnottex +@iftex +(@xref{Permanent Installation, , @code{let} Prevents Confusion}, and +@end iftex @ref{defun, , The @code{defun} Macro}.) -@end ignore @node yank @appendixsec @code{yank} @@ -20000,8 +19954,8 @@ the tic marks themselves and their spacing: @code{defvar}. The @code{boundp} predicate checks whether it has already been set; @code{boundp} returns @code{nil} if it has not. If @code{graph-blank} were unbound and we did not use this conditional -construction, in a recent GNU Emacs, we would enter the debugger and -see an error message saying @samp{@w{Debugger entered--Lisp error:} +construction, we would enter the debugger and see an error message +saying @samp{@w{Debugger entered--Lisp error:} @w{(void-variable graph-blank)}}.) @need 1200 @@ -20821,7 +20775,7 @@ The function @code{1+} which adds one to its argument, is executed on Contrast this with @code{apply}, which applies its first argument to all the remaining. -(@xref{Readying a Graph, , Readying a Graph}, for a explanation of +(@xref{Readying a Graph, , Readying a Graph}, for an explanation of @code{apply}.) @need 1250 @@ -21790,14 +21744,17 @@ MENU ENTRY: NODE NAME. @end ifnottex @quotation -Robert J. Chassell has worked with GNU Emacs since 1985. He writes -and edits, teaches Emacs and Emacs Lisp, and speaks throughout the +Robert J. Chassell (1946--2017) started working with GNU Emacs in 1985. He wrote +and edited, taught Emacs and Emacs Lisp, and spoke throughout the world on software freedom. Chassell was a founding Director and -Treasurer of the Free Software Foundation, Inc. He is co-author of -the @cite{Texinfo} manual, and has edited more than a dozen other -books. He graduated from Cambridge University, in England. He has an -abiding interest in social and economic history and flies his own +Treasurer of the Free Software Foundation, Inc. He was co-author of +the @cite{Texinfo} manual, and edited more than a dozen other +books. He graduated from Cambridge University, in England. He had an +abiding interest in social and economic history and flew his own airplane. + +@uref{https://www.fsf.org/blogs/community/goodbye-to-bob-chassell, +"Goodbye to Bob Chassell"} @end quotation @c @page |