[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to intro.texi
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] Changes to intro.texi |
Date: |
Thu, 06 Sep 2007 04:21:00 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:21:00
Index: intro.texi
===================================================================
RCS file: intro.texi
diff -N intro.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ intro.texi 6 Sep 2007 04:21:00 -0000 1.1
@@ -0,0 +1,560 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003,
2004,
address@hidden 2005, 2006, 2007 Free Software Foundation, Inc.
address@hidden See the file elisp.texi for copying conditions.
address@hidden ../info/intro
+
address@hidden Introduction, Lisp Data Types, Top, Top
address@hidden node-name, next, previous, up
address@hidden 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}.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Caveats
address@hidden Caveats
address@hidden 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.
+
address@hidden
+ 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.
address@hidden iftex
address@hidden
+
+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.
address@hidden ifnottex
+
address@hidden bugs
address@hidden suggestions
+Please mail comments and corrections to
+
address@hidden
+bug-lisp-manual@@gnu.org
address@hidden example
+
address@hidden
+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
address@hidden@@gnu.org}.
+
address@hidden Lisp History
address@hidden Lisp History
address@hidden 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.
+
address@hidden Maclisp
address@hidden 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.
+
address@hidden cl
+ A certain amount of Common Lisp emulation is available via the
address@hidden 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.
+
address@hidden Conventions
address@hidden 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.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Some Terms
address@hidden 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.
+
address@hidden 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}.
+
address@hidden nil and t
address@hidden @code{nil} and @code{t}
address@hidden truth value
address@hidden boolean
+
address@hidden @code{nil}
address@hidden 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
address@hidden; 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.
+
address@hidden
+(cons 'foo ()) ; @r{Emphasize the empty list}
+(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}}
address@hidden example
+
address@hidden @code{t}
address@hidden true
+ In contexts where a truth value is expected, any address@hidden 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
address@hidden
+
+ 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}.
+
address@hidden booleanp object
+Return non-nil if @var{object} is one of the two canonical boolean
+values: @code{t} or @code{nil}.
address@hidden defun
+
address@hidden Evaluation Notation
address@hidden Evaluation Notation
address@hidden evaluation notation
address@hidden documentation notation
address@hidden 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 @address@hidden:
+
address@hidden
+(car '(1 2))
+ @result{} 1
address@hidden example
+
address@hidden
+You can read this as address@hidden(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
address@hidden@expansion{}}. We may or may not show the result of the
+evaluation of the expanded form.
+
address@hidden
+(third '(a b c))
+ @expansion{} (car (cdr (cdr '(a b c))))
+ @result{} c
address@hidden example
+
+ Sometimes to help describe one form we show another form that
+produces identical results. The exact equivalence of two forms is
+indicated with @address@hidden
+
address@hidden
+(make-sparse-keymap) @equiv{} (list 'keymap)
address@hidden example
+
address@hidden Printing Notation
address@hidden Printing Notation
address@hidden 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 @address@hidden,
+irrespective of where that text goes. The value returned by
+evaluating the form (here @code{bar}) follows on a separate line with
address@hidden@result{}}.
+
address@hidden
address@hidden
+(progn (prin1 'foo) (princ "\n") (prin1 'bar))
+ @print{} foo
+ @print{} bar
+ @result{} bar
address@hidden group
address@hidden example
+
address@hidden Error Messages
address@hidden Error Messages
address@hidden 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
address@hidden@error{}}. Note that @address@hidden itself does not appear in
+the echo area.
+
address@hidden
+(+ 23 'x)
address@hidden Wrong type argument: number-or-marker-p, x
address@hidden example
+
address@hidden Buffer Text Notation
address@hidden Buffer Text Notation
address@hidden 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, @address@hidden
+indicates the location of point. (The symbol for point, of course, is
+not part of the text in the buffer; it indicates the place
address@hidden two characters where point is currently located.)
+
address@hidden
+---------- 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 ----------
address@hidden example
+
address@hidden Format of Descriptions
address@hidden Format of Descriptions
address@hidden 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.
address@hidden
+The category---function, variable, or whatever---appears at the
+beginning of the line.
address@hidden ifnottex
address@hidden
+The category---function, variable, or whatever---is printed next to the
+right margin.
address@hidden iftex
+The description follows on succeeding lines, sometimes with examples.
+
address@hidden
+* 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}.
address@hidden menu
+
address@hidden A Sample Function Description
address@hidden A Sample Function Description
address@hidden function descriptions
address@hidden command descriptions
address@hidden macro descriptions
address@hidden 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}:
+
address@hidden 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.
+
address@hidden
+(foo 1 5 3 9)
+ @result{} 16
+(foo 5)
+ @result{} 14
address@hidden example
+
address@hidden 1500
+More generally,
+
address@hidden
+(foo @var{w} @var{x} @address@hidden)
address@hidden
+(+ (- @var{x} @var{w}) @address@hidden)
address@hidden example
address@hidden defun
+
+ Any argument whose name contains the name of a type (e.g.,
address@hidden, @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.
address@hidden@address@hidden@r{]}} means that @var{optional-arg} is
+optional and @address@hidden@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:
+
address@hidden count-loop (@var{var} address@hidden @var{to} address@hidden)
@address@hidden
+This imaginary special form implements a loop that executes the
address@hidden forms and then increments the variable @var{var} on each
+iteration. On the first iteration, the variable has the value
address@hidden; on subsequent iterations, it is incremented by one (or by
address@hidden if that is given). The loop exits before executing @var{body}
+if @var{var} equals @var{to}. Here is an example:
+
address@hidden
+(count-loop (i 0 10)
+ (prin1 i) (princ " ")
+ (prin1 (aref vector i))
+ (terpri))
address@hidden example
+
+If @var{from} and @var{to} are omitted, @var{var} is bound to
address@hidden before the loop begins, and the loop exits if @var{var} is
address@hidden at the beginning of an iteration. Here is an example:
+
address@hidden
+(count-loop (done)
+ (if (pending)
+ (fixit)
+ (setq done t)))
address@hidden 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,
address@hidden 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.
address@hidden defspec
+
address@hidden A Sample Variable Description
address@hidden A Sample Variable Description
address@hidden variable descriptions
address@hidden 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}
address@hidden
+
address@hidden 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.
address@hidden defvar
+
+ User option descriptions have the same format, but `Variable' is
+replaced by `User Option'.
+
address@hidden Version Info
address@hidden Version Information
+
+ These facilities provide information about which version of Emacs is
+in use.
+
address@hidden 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.
+
address@hidden
address@hidden
+(emacs-version)
+ @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
+ of Sat Feb 14 1998 on psilocin.gnu.org"
address@hidden group
address@hidden smallexample
+
+If @var{here} is address@hidden, 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} address@hidden
address@hidden deffn
+
address@hidden 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}).
+
address@hidden
address@hidden
+emacs-build-time
+ @result{} (13623 62065 344633)
address@hidden group
address@hidden example
address@hidden defvar
+
address@hidden 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.
address@hidden defvar
+
+ The following two variables have existed since Emacs version 19.23:
+
address@hidden emacs-major-version
+The major version number of Emacs, as an integer. For Emacs version
+20.3, the value is 20.
address@hidden defvar
+
address@hidden emacs-minor-version
+The minor version number of Emacs, as an integer. For Emacs version
+20.3, the value is 3.
address@hidden defvar
+
address@hidden Acknowledgements
address@hidden Acknowledgements
+
+ This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte,
address@hidden Stallman and Chris Welty, the volunteers of the GNU
+manual group, in an effort extending over several years.
address@hidden Chassell helped to review and edit the manual, with the
+support of the Defense Advanced Research Projects Agency, ARPA Order
+6082, arranged by address@hidden 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.
+
address@hidden
+ arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa
address@hidden ignore