@syncodeindex fn cp
@finalout
-@c ---------
+@include emacsver.texi
+
+@c ================ How to Print a Book in Various Sizes ================
+
+@c This book can be printed in any of three different sizes.
+@c Set the following @-commands appropriately.
+
+@c 7 by 9.25 inches:
+@c @smallbook
+@c @clear largebook
+
+@c 8.5 by 11 inches:
+@c @c smallbook
+@c @set largebook
+
+@c European A4 size paper:
+@c @c smallbook
+@c @afourpaper
+@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 <<<< For hard copy printing, this file is now
@c set for smallbook, which works for all sizes
@c of paper, and with PostScript figures >>>>
+
@set smallbook
@ifset smallbook
@smallbook
@clear largebook
@end ifset
+
+@c ================ Included Figures ================
+
+@c If you clear this, the figures will be printed as ASCII diagrams
+@c rather than PostScript/PDF.
+@c (This is not relevant to Info, since Info only handles ASCII.)
@set print-postscript-figures
-@c set largebook
@c clear print-postscript-figures
-@c ---------
@comment %**end of header
\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
-@ignore
- ## Summary of shell commands to create various output formats:
-
- pushd /usr/local/src/emacs/lispintro/
- ## pushd /u/intro/
-
- ## Info output
- makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi
-
- ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr"))
-
- ## DVI output
- texi2dvi emacs-lisp-intro.texi
-
- ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
-
- ## HTML output
- makeinfo --html --no-split --verbose emacs-lisp-intro.texi
-
- ## galeon emacs-lisp-intro.html
-
- ## Plain text output
- makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
- --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
-
- popd
-
-# as user `root'
-# insert thumbdrive
- mtusb # mount -v -t ext3 /dev/sda /mnt
- cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
- umtusb # umount -v /mnt
-# remove thumbdrive
-
- ## Other shell commands
-
- pushd /usr/local/src/emacs/lispintro/
- ## pushd /u/intro/
-
- ## PDF
- texi2dvi --pdf emacs-lisp-intro.texi
- # xpdf emacs-lisp-intro.pdf &
-
- ## DocBook -- note file extension
- makeinfo --docbook --no-split --paragraph-indent=0 \
- --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi
-
- ## XML with a Texinfo DTD -- note file extension
- makeinfo --xml --no-split --paragraph-indent=0 \
- --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi
-
- ## PostScript (needs DVI)
- # gv emacs-lisp-intro.ps &
- # Create DVI if we lack it
- # texi2dvi emacs-lisp-intro.texi
- dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps
-
- ## RTF (needs HTML)
- # Use OpenOffice to view RTF
- # Create HTML if we lack it
- # makeinfo --no-split --html emacs-lisp-intro.texi
- /usr/local/src/html2rtf.pl emacs-lisp-intro.html
-
- ## LaTeX (needs RTF)
- /usr/bin/rtf2latex emacs-lisp-intro.rtf
-
- popd
-
-@end ignore
-
-@c ================ Included Figures ================
-
-@c Set print-postscript-figures if you print PostScript figures.
-@c If you clear this, the ten figures will be printed as ASCII diagrams.
-@c (This is not relevant to Info, since Info only handles ASCII.)
-@c Your site may require editing changes to print PostScript; in this
-@c case, search for `print-postscript-figures' and make appropriate changes.
-
-@c ================ How to Create an Info file ================
-
-@c If you have `makeinfo' installed, run the following command
-
-@c makeinfo emacs-lisp-intro.texi
-
-@c or, if you want a single, large Info file, and no paragraph indents:
-@c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
-
-@c After creating the Info file, edit your Info `dir' file, if the
-@c `dircategory' section below does not enable your system to
-@c install the manual automatically.
-@c (The `dir' file is often in the `/usr/local/share/info/' directory.)
-
-@c ================ How to Create an HTML file ================
-
-@c To convert to HTML format
-@c makeinfo --html --no-split --verbose emacs-lisp-intro.texi
-
-@c ================ How to Print a Book in Various Sizes ================
-
-@c This book can be printed in any of three different sizes.
-@c In the above header, set @-commands appropriately.
-
-@c 7 by 9.25 inches:
-@c @smallbook
-@c @clear largebook
-
-@c 8.5 by 11 inches:
-@c @c smallbook
-@c @set largebook
-
-@c European A4 size paper:
-@c @c smallbook
-@c @afourpaper
-@c @set largebook
-
-@c ================ How to Typeset and Print ================
-
-@c If you do not include PostScript figures, run either of the
-@c following command sequences, or similar commands suited to your
-@c system:
-
-@c texi2dvi emacs-lisp-intro.texi
-@c lpr -d emacs-lisp-intro.dvi
-
-@c or else:
-
-@c tex emacs-lisp-intro.texi
-@c texindex emacs-lisp-intro.??
-@c tex emacs-lisp-intro.texi
-@c lpr -d emacs-lisp-intro.dvi
-
-@c If you include the PostScript figures, and you have old software,
-@c you may need to convert the .dvi file to a .ps file before
-@c printing. Run either of the following command sequences, or one
-@c similar:
-@c
-@c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
-@c
-@c or else:
-@c
-@c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
-@c
-
-@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 ================ End of Formatting Sections ================
-
@c For next or subsequent edition:
@c create function using with-output-to-temp-buffer
@c create a major mode, with keymaps
This is an @cite{Introduction to Programming in Emacs Lisp}, for
people who are not programmers.
@sp 1
+@iftex
Edition @value{edition-number}, @value{update-date}
+@end iftex
+@ifnottex
+Distributed with Emacs version @value{EMACSVER}.
+@end ifnottex
@sp 1
Copyright @copyright{} 1990--1995, 1997, 2001--2013 Free Software
Foundation, Inc.
@iftex
Published by the:@*
-GNU Press, @hfill @uref{http://www.fsf.org/campaigns/gnu-press/}@*
+GNU Press, @hfill @uref{http://www.fsf.org/licensing/gnu-press/}@*
a division of the @hfill email: @email{sales@@fsf.org}@*
Free Software Foundation, Inc. @hfill Tel: +1 (617) 542-5942@*
51 Franklin Street, Fifth Floor @hfill Fax: +1 (617) 542-2652@*
@end iftex
@ifnottex
-Published by the:
+Printed copies available from @uref{http://shop.fsf.org/}. Published by:
@example
-GNU Press, http://www.fsf.org/campaigns/gnu-press/
+GNU Press, http://www.fsf.org/licensing/gnu-press/
a division of the email: sales@@fsf.org
Free Software Foundation, Inc. Tel: +1 (617) 542-5942
51 Franklin Street, Fifth Floor Fax: +1 (617) 542-2652
@end ifnottex
@sp 1
-@c Printed copies are available from @uref{http://shop.fsf.org/} for $35 each.@*
ISBN 1-882114-43-4
Permission is granted to copy, distribute and/or modify this document
How To Write Function Definitions
* Primitive Functions::
-* defun:: The @code{defun} special form.
+* defun:: The @code{defun} macro.
* Install:: Install a function definition.
* Interactive:: Making a function interactive.
* Interactive Options:: Different options for @code{interactive}.
* Default Configuration::
* Site-wide Init:: You can write site-wide init files.
* defcustom:: Emacs will write code for you.
-* Beginning a .emacs File:: How to write a @code{.emacs file}.
+* Beginning init File:: How to write a @file{.emacs} init file.
* Text and Auto-fill:: Automatically wrap lines.
* Mail Aliases:: Use abbreviations for email addresses.
* Indent Tabs Mode:: Don't use tabs with @TeX{}
in the section on variables. (@xref{Variables}.)
@cindex Special form
-The second complication occurs because some functions are unusual and do
-not work in the usual manner. Those that don't are called @dfn{special
-forms}. They are used for special jobs, like defining a function, and
-there are not many of them. In the next few chapters, you will be
-introduced to several of the more important special forms.
-
-The third and final complication is this: if the function that the
+The second complication occurs because some functions are unusual and
+do not work in the usual manner. Those that don't are called
+@dfn{special forms}. They are used for special jobs, like defining a
+function, and there are not many of them. In the next few chapters,
+you will be introduced to several of the more important special forms.
+
+As well as special forms, there are also @dfn{macros}. A macro
+is a construct defined in Lisp, which differs from a function in that it
+translates a Lisp expression into another expression that is to be
+evaluated in place of the original expression. (@xref{Lisp macro}.)
+
+For the purposes of this introduction, you do not need to worry too much
+about whether something is a special form, macro, or ordinary function.
+For example, @code{if} is a special form (@pxref{if}), but @code{when}
+is a macro (@pxref{Lisp macro}). In earlier versions of Emacs,
+@code{defun} was a special form, but now it is a macro (@pxref{defun}).
+It still behaves in the same way.
+
+The final complication is this: if the function that the
Lisp interpreter is looking at is not a special form, and if it is part
of a list, the Lisp interpreter looks to see whether the list has a list
inside of it. If there is an inner list, the Lisp interpreter first
@menu
* Primitive Functions::
-* defun:: The @code{defun} special form.
+* defun:: The @code{defun} macro.
* Install:: Install a function definition.
* Interactive:: Making a function interactive.
* Interactive Options:: Different options for @code{interactive}.
function is written in Emacs Lisp or C.
@node defun
-@section The @code{defun} Special Form
+@section The @code{defun} Macro
@findex defun
-@cindex Special form of @code{defun}
@cindex @samp{function definition} defined
In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
it that tells the computer what to do when the function is called.
This code is called the @dfn{function definition} and is created by
evaluating a Lisp expression that starts with the symbol @code{defun}
-(which is an abbreviation for @emph{define function}). Because
-@code{defun} does not evaluate its arguments in the usual way, it is
-called a @dfn{special form}.
+(which is an abbreviation for @emph{define function}).
In subsequent sections, we will look at function definitions from the
Emacs source code, such as @code{mark-whole-buffer}. In this section,
end of the comment. To stretch a comment over two or more lines, begin
each line with a semicolon.
-@xref{Beginning a .emacs File, , Beginning a @file{.emacs}
+@xref{Beginning init File, , Beginning a @file{.emacs}
File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
Reference Manual}, for more about comments.
name outside the @code{let} expression. This is like understanding
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} Special Form}.)
+@xref{defun, , The @code{defun} Macro}.)
Local variables created by a @code{let} expression retain their value
@emph{only} within the @code{let} expression itself (and within
@findex point
@findex mark
-The @code{save-excursion} function is the fourth and final special form
+The @code{save-excursion} function is the third and final special form
that we will discuss in this chapter.
In Emacs Lisp programs used for editing, the @code{save-excursion}
@node Review
@section Review
-In the last few chapters we have introduced a fair number of functions
-and special forms. Here they are described in brief, along with a few
-similar functions that have not been mentioned yet.
+In the last few chapters we have introduced a macro and a fair number
+of functions and special forms. Here they are described in brief,
+along with a few similar functions that have not been mentioned yet.
@table @code
@item eval-last-sexp
current buffer. This command is normally bound to @kbd{C-x C-e}.
@item defun
-Define function. This special form has up to five parts: the name,
-a template for the arguments that will be passed to the function,
-documentation, an optional interactive declaration, and the body of the
-definition.
+Define function. This macro has up to five parts: the name, a
+template for the arguments that will be passed to the function,
+documentation, an optional interactive declaration, and the body of
+the definition.
@need 1250
For example, in an early version of Emacs, the function definition was
@end smallexample
Like all function definitions, this definition has five parts following
-the special form @code{defun}:
+the macro @code{defun}:
@enumerate
@item
@section @code{zap-to-char}
@findex zap-to-char
-@c FIXME remove obsolete stuff
-The @code{zap-to-char} function changed little between GNU Emacs
-version 19 and GNU Emacs version 22. However, @code{zap-to-char}
-calls another function, @code{kill-region}, which enjoyed a major
-rewrite.
-
-The @code{kill-region} function in Emacs 19 is complex, but does not
-use code that is important at this time. We will skip it.
-
-The @code{kill-region} function in Emacs 22 is easier to read than the
-same function in Emacs 19 and introduces a very important concept,
-that of error handling. We will walk through the function.
-
-But first, let us look at the interactive @code{zap-to-char} function.
+Let us look at the interactive @code{zap-to-char} function.
@menu
* Complete zap-to-char:: The complete implementation.
you can replace @code{when} with @code{if} and understand what goes
on. That is what the Lisp interpreter does.
-Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro}
+Technically speaking, @code{when} is a Lisp macro. A Lisp macro
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
not override the existing value. Second, @code{defvar} has a
documentation string.
-(Another special form, @code{defcustom}, is designed for variables
+(There is a related macro, @code{defcustom}, designed for variables
that people customize. It has more features than @code{defvar}.
(@xref{defcustom, , Setting Variables with @code{defcustom}}.)
internal variables that you would not expect a user to change and for
variables that you do expect a user to change. Although you can still
use @code{defvar} for user customizable variables, please use
-@code{defcustom} instead, since that special form provides a path into
+@code{defcustom} instead, since it provides a path into
the Customization commands. (@xref{defcustom, , Specifying Variables
using @code{defcustom}}.)
@sp 1
@tex
@center @image{cons-1}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
@sp 1
@tex
@center @image{cons-2}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
@sp 1
@tex
@center @image{cons-2a}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
@sp 1
@tex
@center @image{cons-3}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
@sp 1
@tex
@center @image{cons-4}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
@sp 1
@tex
@center @image{drawers}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
@sp 1
@tex
@center @image{cons-5}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
A function definition provides the blueprints for a robot. When you
install a function definition, that is, when you evaluate a
-@code{defun} special form, 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'.
+@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'.
We often say that a recursive function `calls itself'. What we mean
is that the instructions in a recursive function cause the Lisp
"-rw-r--r--"
@end group
@group
-nil
+t
2971624
773)
@end group
* Default Configuration::
* Site-wide Init:: You can write site-wide init files.
* defcustom:: Emacs will write code for you.
-* Beginning a .emacs File:: How to write a @code{.emacs file}.
+* Beginning init File:: How to write a @file{.emacs} init file.
* Text and Auto-fill:: Automatically wrap lines.
* Mail Aliases:: Use abbreviations for email addresses.
* Indent Tabs Mode:: Don't use tabs with @TeX{}
file. Indeed, you can write any Lisp expression in your @file{.emacs}
file.)
-The @code{customize} feature depends on the @code{defcustom} special
-form. Although you can use @code{defvar} or @code{setq} for variables
-that users set, the @code{defcustom} special form is designed for the
-job.
+The @code{customize} feature depends on the @code{defcustom} macro.
+Although you can use @code{defvar} or @code{setq} for variables that
+users set, the @code{defcustom} macro is designed for the job.
You can use your knowledge of @code{defvar} for writing the
first three arguments for @code{defcustom}. The first argument to
command in which group the variable is located. This tells where to
find it.
-The @code{defcustom} function recognizes more than a dozen keywords.
+The @code{defcustom} macro recognizes more than a dozen keywords.
For more information, see @ref{Customization, , Writing Customization
Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
set by @code{defconst}. (You can change it; the value set is a
variable; but please do not.)
-@node Beginning a .emacs File
+@node Beginning init File
@section Beginning a @file{.emacs} File
@cindex @file{.emacs} file, beginning of
@ignore
@c texi2dvi fails when the name of the section is within ifnottex ...
(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
-@ref{defun, , The @code{defun} Special Form}.)
+@ref{defun, , The @code{defun} Macro}.)
@end ignore
@node yank
@end smallexample
@noindent
-(@xref{defun, , The @code{defun} Special Form}.)
+(@xref{defun, , The @code{defun} Macro}.)
@need 1250
@noindent
If we want to multiply 3 by 7, we can write:
-@c !!! Clear print-postscript-figures if the computer formatting this
-@c document is too small and cannot handle all the diagrams and figures.
@c clear print-postscript-figures
-@c set print-postscript-figures
@c lambda example diagram #1
@ifnottex
@smallexample
@sp 1
@tex
@center @image{lambda-1}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
@sp 1
@tex
@center @image{lambda-2}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset
@sp 1
@tex
@center @image{lambda-3}
-%%%% old method of including an image
-% \input /usr/local/lib/tex/inputs/psfig.tex
-% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
-% \catcode`\@=0 %
@end tex
@sp 1
@end ifset