Move here from ../../lispref

1 files changed, 560 insertions, 0 deletions

diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
new file mode 100644
index 00000000000..ed0fd1c0699
--- /dev/null
+++ b/doc/lispref/intro.texi
@@ -0,0 +1,560 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/intro
+
+@node Introduction, Lisp Data Types, Top, Top
+@comment  node-name,  next,  previous,  up
+@chapter Introduction
+
+  Most of the GNU Emacs text editor is written in the programming
+language called Emacs Lisp.  You can write new code in Emacs Lisp and
+install it as an extension to the editor.  However, Emacs Lisp is more
+than a mere ``extension language''; it is a full computer programming
+language in its own right.  You can use it as you would any other
+programming language.
+
+  Because Emacs Lisp is designed for use in an editor, it has special
+features for scanning and parsing text as well as features for handling
+files, buffers, displays, subprocesses, and so on.  Emacs Lisp is
+closely integrated with the editing facilities; thus, editing commands
+are functions that can also conveniently be called from Lisp programs,
+and parameters for customization are ordinary Lisp variables.
+
+  This manual attempts to be a full description of Emacs Lisp.  For a
+beginner's introduction to Emacs Lisp, see @cite{An Introduction to
+Emacs Lisp Programming}, by Bob Chassell, also published by the Free
+Software Foundation.  This manual presumes considerable familiarity with
+the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this
+basic information.
+
+  Generally speaking, the earlier chapters describe features of Emacs
+Lisp that have counterparts in many programming languages, and later
+chapters describe features that are peculiar to Emacs Lisp or relate
+specifically to editing.
+
+  This is edition @value{VERSION} of the GNU Emacs Lisp Reference
+Manual, corresponding to Emacs version @value{EMACSVER}.
+
+@menu
+* Caveats::             Flaws and a request for help.
+* Lisp History::        Emacs Lisp is descended from Maclisp.
+* Conventions::         How the manual is formatted.
+* Version Info::        Which Emacs version is running?
+* Acknowledgements::    The authors, editors, and sponsors of this manual.
+@end menu
+
+@node Caveats
+@section Caveats
+@cindex bugs in this manual
+
+  This manual has gone through numerous drafts.  It is nearly complete
+but not flawless.  There are a few topics that are not covered, either
+because we consider them secondary (such as most of the individual
+modes) or because they are yet to be written.  Because we are not able
+to deal with them completely, we have left out several parts
+intentionally.  This includes most information about usage on VMS.
+
+  The manual should be fully correct in what it does cover, and it is
+therefore open to criticism on anything it says---from specific examples
+and descriptive text, to the ordering of chapters and sections.  If
+something is confusing, or you find that you have to look at the sources
+or experiment to learn something not covered in the manual, then perhaps
+the manual should be fixed.  Please let us know.
+
+@iftex
+  As you use this manual, we ask that you mark pages with corrections so
+you can later look them up and send them to us.  If you think of a simple,
+real-life example for a function or group of functions, please make an
+effort to write it up and send it in.  Please reference any comments to
+the chapter name, section name, and function name, as appropriate, since
+page numbers and chapter and section numbers will change and we may have
+trouble finding the text you are talking about.  Also state the number
+of the edition you are criticizing.
+@end iftex
+@ifnottex
+
+As you use this manual, we ask that you send corrections as soon as you
+find them.  If you think of a simple, real life example for a function
+or group of functions, please make an effort to write it up and send it
+in.  Please reference any comments to the node name and function or
+variable name, as appropriate.  Also state the number of the edition
+you are criticizing.
+@end ifnottex
+
+@cindex bugs
+@cindex suggestions
+Please mail comments and corrections to
+
+@example
+bug-lisp-manual@@gnu.org
+@end example
+
+@noindent
+We let mail to this list accumulate unread until someone decides to
+apply the corrections.  Months, and sometimes years, go by between
+updates.  So please attach no significance to the lack of a reply---your
+mail @emph{will} be acted on in due time.  If you want to contact the
+Emacs maintainers more quickly, send mail to
+@code{bug-gnu-emacs@@gnu.org}.
+
+@node Lisp History
+@section Lisp History
+@cindex Lisp history
+
+  Lisp (LISt Processing language) was first developed in the late 1950s
+at the Massachusetts Institute of Technology for research in artificial
+intelligence.  The great power of the Lisp language makes it ideal
+for other purposes as well, such as writing editing commands.
+
+@cindex Maclisp
+@cindex Common Lisp
+  Dozens of Lisp implementations have been built over the years, each
+with its own idiosyncrasies.  Many of them were inspired by Maclisp,
+which was written in the 1960s at MIT's Project MAC.  Eventually the
+implementors of the descendants of Maclisp came together and developed a
+standard for Lisp systems, called Common Lisp.  In the meantime, Gerry
+Sussman and Guy Steele at MIT developed a simplified but very powerful
+dialect of Lisp, called Scheme.
+
+  GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
+Lisp.  If you know Common Lisp, you will notice many similarities.
+However, many features of Common Lisp have been omitted or
+simplified in order to reduce the memory requirements of GNU Emacs.
+Sometimes the simplifications are so drastic that a Common Lisp user
+might be very confused.  We will occasionally point out how GNU Emacs
+Lisp differs from Common Lisp.  If you don't know Common Lisp, don't
+worry about it; this manual is self-contained.
+
+@pindex cl
+  A certain amount of Common Lisp emulation is available via the
+@file{cl} library.  @inforef{Top, Overview, cl}.
+
+  Emacs Lisp is not at all influenced by Scheme; but the GNU project has
+an implementation of Scheme, called Guile.  We use Guile in all new GNU
+software that calls for extensibility.
+
+@node Conventions
+@section Conventions
+
+This section explains the notational conventions that are used in this
+manual.  You may want to skip this section and refer back to it later.
+
+@menu
+* Some Terms::               Explanation of terms we use in this manual.
+* nil and t::                How the symbols @code{nil} and @code{t} are used.
+* Evaluation Notation::      The format we use for examples of evaluation.
+* Printing Notation::        The format we use when examples print text.
+* Error Messages::           The format we use for examples of errors.
+* Buffer Text Notation::     The format we use for buffer contents in examples.
+* Format of Descriptions::   Notation for describing functions, variables, etc.
+@end menu
+
+@node Some Terms
+@subsection Some Terms
+
+  Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
+printer'' refer to those routines in Lisp that convert textual
+representations of Lisp objects into actual Lisp objects, and vice
+versa.  @xref{Printed Representation}, for more details.  You, the
+person reading this manual, are thought of as ``the programmer'' and are
+addressed as ``you.''  ``The user'' is the person who uses Lisp
+programs, including those you write.
+
+@cindex fonts in this manual
+  Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
+Names that represent metasyntactic variables, or arguments to a function
+being described, are formatted like this: @var{first-number}.
+
+@node nil and t
+@subsection @code{nil} and @code{t}
+@cindex truth value
+@cindex boolean
+
+@cindex @code{nil}
+@cindex false
+  In Lisp, the symbol @code{nil} has three separate meanings: it
+is a symbol with the name @samp{nil}; it is the logical truth value
+@var{false}; and it is the empty list---the list of zero elements.
+When used as a variable, @code{nil} always has the value @code{nil}.
+
+  As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are
+identical: they stand for the same object, the symbol @code{nil}.  The
+different ways of writing the symbol are intended entirely for human
+readers.  After the Lisp reader has read either @samp{()} or @samp{nil},
+there is no way to determine which representation was actually written
+by the programmer.
+
+  In this manual, we write @code{()} when we wish to emphasize that it
+means the empty list, and we write @code{nil} when we wish to emphasize
+that it means the truth value @var{false}.  That is a good convention to use
+in Lisp programs also.
+
+@example
+(cons 'foo ())                ; @r{Emphasize the empty list}
+(setq foo-flag nil)           ; @r{Emphasize the truth value @var{false}}
+@end example
+
+@cindex @code{t}
+@cindex true
+  In contexts where a truth value is expected, any non-@code{nil} value
+is considered to be @var{true}.  However, @code{t} is the preferred way
+to represent the truth value @var{true}.  When you need to choose a
+value which represents @var{true}, and there is no other basis for
+choosing, use @code{t}.  The symbol @code{t} always has the value
+@code{t}.
+
+  In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
+evaluate to themselves.  This is so that you do not need to quote them
+to use them as constants in a program.  An attempt to change their
+values results in a @code{setting-constant} error.  @xref{Constant
+Variables}.
+
+@defun booleanp object
+Return non-nil if @var{object} is one of the two canonical boolean
+values: @code{t} or @code{nil}.
+@end defun
+
+@node Evaluation Notation
+@subsection Evaluation Notation
+@cindex evaluation notation
+@cindex documentation notation
+@cindex notation
+
+  A Lisp expression that you can evaluate is called a @dfn{form}.
+Evaluating a form always produces a result, which is a Lisp object.  In
+the examples in this manual, this is indicated with @samp{@result{}}:
+
+@example
+(car '(1 2))
+     @result{} 1
+@end example
+
+@noindent
+You can read this as ``@code{(car '(1 2))} evaluates to 1.''
+
+  When a form is a macro call, it expands into a new form for Lisp to
+evaluate.  We show the result of the expansion with
+@samp{@expansion{}}.  We may or may not show the result of the
+evaluation of the expanded form.
+
+@example
+(third '(a b c))
+     @expansion{} (car (cdr (cdr '(a b c))))
+     @result{} c
+@end example
+
+  Sometimes to help describe one form we show another form that
+produces identical results.  The exact equivalence of two forms is
+indicated with @samp{@equiv{}}.
+
+@example
+(make-sparse-keymap) @equiv{} (list 'keymap)
+@end example
+
+@node Printing Notation
+@subsection Printing Notation
+@cindex printing notation
+
+  Many of the examples in this manual print text when they are
+evaluated.  If you execute example code in a Lisp Interaction buffer
+(such as the buffer @samp{*scratch*}), the printed text is inserted into
+the buffer.  If you execute the example by other means (such as by
+evaluating the function @code{eval-region}), the printed text is
+displayed in the echo area.
+
+  Examples in this manual indicate printed text with @samp{@print{}},
+irrespective of where that text goes.  The value returned by
+evaluating the form (here @code{bar}) follows on a separate line with
+@samp{@result{}}.
+
+@example
+@group
+(progn (prin1 'foo) (princ "\n") (prin1 'bar))
+     @print{} foo
+     @print{} bar
+     @result{} bar
+@end group
+@end example
+
+@node Error Messages
+@subsection Error Messages
+@cindex error message notation
+
+  Some examples signal errors.  This normally displays an error message
+in the echo area.  We show the error message on a line starting with
+@samp{@error{}}.  Note that @samp{@error{}} itself does not appear in
+the echo area.
+
+@example
+(+ 23 'x)
+@error{} Wrong type argument: number-or-marker-p, x
+@end example
+
+@node Buffer Text Notation
+@subsection Buffer Text Notation
+@cindex buffer text notation
+
+  Some examples describe modifications to the contents of a buffer, by
+showing the ``before'' and ``after'' versions of the text.  These
+examples show the contents of the buffer in question between two lines
+of dashes containing the buffer name.  In addition, @samp{@point{}}
+indicates the location of point.  (The symbol for point, of course, is
+not part of the text in the buffer; it indicates the place
+@emph{between} two characters where point is currently located.)
+
+@example
+---------- Buffer: foo ----------
+This is the @point{}contents of foo.
+---------- Buffer: foo ----------
+
+(insert "changed ")
+     @result{} nil
+---------- Buffer: foo ----------
+This is the changed @point{}contents of foo.
+---------- Buffer: foo ----------
+@end example
+
+@node Format of Descriptions
+@subsection Format of Descriptions
+@cindex description format
+
+  Functions, variables, macros, commands, user options, and special
+forms are described in this manual in a uniform format.  The first
+line of a description contains the name of the item followed by its
+arguments, if any.
+@ifnottex
+The category---function, variable, or whatever---appears at the
+beginning of the line.
+@end ifnottex
+@iftex
+The category---function, variable, or whatever---is printed next to the
+right margin.
+@end iftex
+The description follows on succeeding lines, sometimes with examples.
+
+@menu
+* A Sample Function Description::       A description of an imaginary
+                                          function, @code{foo}.
+* A Sample Variable Description::       A description of an imaginary
+                                          variable,
+                                          @code{electric-future-map}.
+@end menu
+
+@node A Sample Function Description
+@subsubsection A Sample Function Description
+@cindex function descriptions
+@cindex command descriptions
+@cindex macro descriptions
+@cindex special form descriptions
+
+  In a function description, the name of the function being described
+appears first.  It is followed on the same line by a list of argument
+names.  These names are also used in the body of the description, to
+stand for the values of the arguments.
+
+  The appearance of the keyword @code{&optional} in the argument list
+indicates that the subsequent arguments may be omitted (omitted
+arguments default to @code{nil}).  Do not write @code{&optional} when
+you call the function.
+
+  The keyword @code{&rest} (which must be followed by a single
+argument name) indicates that any number of arguments can follow.  The
+single argument name following @code{&rest} will receive, as its
+value, a list of all the remaining arguments passed to the function.
+Do not write @code{&rest} when you call the function.
+
+  Here is a description of an imaginary function @code{foo}:
+
+@defun foo integer1 &optional integer2 &rest integers
+The function @code{foo} subtracts @var{integer1} from @var{integer2},
+then adds all the rest of the arguments to the result.  If @var{integer2}
+is not supplied, then the number 19 is used by default.
+
+@example
+(foo 1 5 3 9)
+     @result{} 16
+(foo 5)
+     @result{} 14
+@end example
+
+@need 1500
+More generally,
+
+@example
+(foo @var{w} @var{x} @var{y}@dots{})
+@equiv{}
+(+ (- @var{x} @var{w}) @var{y}@dots{})
+@end example
+@end defun
+
+  Any argument whose name contains the name of a type (e.g.,
+@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
+type.  A plural of a type (such as @var{buffers}) often means a list of
+objects of that type.  Arguments named @var{object} may be of any type.
+(@xref{Lisp Data Types}, for a list of Emacs object types.)  Arguments
+with other sorts of names (e.g., @var{new-file}) are discussed
+specifically in the description of the function.  In some sections,
+features common to the arguments of several functions are described at
+the beginning.
+
+  @xref{Lambda Expressions}, for a more complete description of optional
+and rest arguments.
+
+  Command, macro, and special form descriptions have the same format,
+but the word `Function' is replaced by `Command', `Macro', or `Special
+Form', respectively.  Commands are simply functions that may be called
+interactively; macros process their arguments differently from functions
+(the arguments are not evaluated), but are presented the same way.
+
+  Special form descriptions use a more complex notation to specify
+optional and repeated arguments because they can break the argument
+list down into separate arguments in more complicated ways.
+@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
+optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
+arguments.  Parentheses are used when several arguments are grouped into
+additional levels of list structure.  Here is an example:
+
+@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
+This imaginary special form implements a loop that executes the
+@var{body} forms and then increments the variable @var{var} on each
+iteration.  On the first iteration, the variable has the value
+@var{from}; on subsequent iterations, it is incremented by one (or by
+@var{inc} if that is given).  The loop exits before executing @var{body}
+if @var{var} equals @var{to}.  Here is an example:
+
+@example
+(count-loop (i 0 10)
+  (prin1 i) (princ " ")
+  (prin1 (aref vector i))
+  (terpri))
+@end example
+
+If @var{from} and @var{to} are omitted, @var{var} is bound to
+@code{nil} before the loop begins, and the loop exits if @var{var} is
+non-@code{nil} at the beginning of an iteration.  Here is an example:
+
+@example
+(count-loop (done)
+  (if (pending)
+      (fixit)
+    (setq done t)))
+@end example
+
+In this special form, the arguments @var{from} and @var{to} are
+optional, but must both be present or both absent.  If they are present,
+@var{inc} may optionally be specified as well.  These arguments are
+grouped with the argument @var{var} into a list, to distinguish them
+from @var{body}, which includes all remaining elements of the form.
+@end defspec
+
+@node A Sample Variable Description
+@subsubsection A Sample Variable Description
+@cindex variable descriptions
+@cindex option descriptions
+
+  A @dfn{variable} is a name that can hold a value.  Although nearly
+all variables can be set by the user, certain variables exist
+specifically so that users can change them; these are called @dfn{user
+options}.  Ordinary variables and user options are described using a
+format like that for functions except that there are no arguments.
+
+  Here is a description of the imaginary @code{electric-future-map}
+variable.@refill
+
+@defvar electric-future-map
+The value of this variable is a full keymap used by Electric Command
+Future mode.  The functions in this map allow you to edit commands you
+have not yet thought about executing.
+@end defvar
+
+  User option descriptions have the same format, but `Variable' is
+replaced by `User Option'.
+
+@node Version Info
+@section Version Information
+
+  These facilities provide information about which version of Emacs is
+in use.
+
+@deffn Command emacs-version &optional here
+This function returns a string describing the version of Emacs that is
+running.  It is useful to include this string in bug reports.
+
+@smallexample
+@group
+(emacs-version)
+  @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
+ of Sat Feb 14 1998 on psilocin.gnu.org"
+@end group
+@end smallexample
+
+If @var{here} is non-@code{nil}, it inserts the text in the buffer
+before point, and returns @code{nil}.  Called interactively, the
+function prints the same information in the echo area, but giving a
+prefix argument makes @var{here} non-@code{nil}.
+@end deffn
+
+@defvar emacs-build-time
+The value of this variable indicates the time at which Emacs was built
+at the local site.  It is a list of three integers, like the value
+of @code{current-time} (@pxref{Time of Day}).
+
+@example
+@group
+emacs-build-time
+     @result{} (13623 62065 344633)
+@end group
+@end example
+@end defvar
+
+@defvar emacs-version
+The value of this variable is the version of Emacs being run.  It is a
+string such as @code{"20.3.1"}.  The last number in this string is not
+really part of the Emacs release version number; it is incremented each
+time you build Emacs in any given directory.  A value with four numeric
+components, such as @code{"20.3.9.1"}, indicates an unreleased test
+version.
+@end defvar
+
+  The following two variables have existed since Emacs version 19.23:
+
+@defvar emacs-major-version
+The major version number of Emacs, as an integer.  For Emacs version
+20.3, the value is 20.
+@end defvar
+
+@defvar emacs-minor-version
+The minor version number of Emacs, as an integer.  For Emacs version
+20.3, the value is 3.
+@end defvar
+
+@node Acknowledgements
+@section Acknowledgements
+
+  This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte,
+Richard@tie{}M. Stallman and Chris Welty, the volunteers of the GNU
+manual group, in an effort extending over several years.
+Robert@tie{}J. Chassell helped to review and edit the manual, with the
+support of the Defense Advanced Research Projects Agency, ARPA Order
+6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic,
+Inc.
+
+  Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom,
+Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence
+R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly
+Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea,
+Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki
+Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe
+Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland
+McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson,
+Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul
+Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp,
+Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty,
+Dale Worley, Rusty Wright, and David D. Zuhn.
+
+@ignore
+   arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa
+@end ignore