comparison lispref/intro.texi @ 88155:d7ddb3e565de

sync with trunk

88154:8ce476d3ba36

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002
@c   Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/intro

@c Versino of the manual.
@set VERSION 2.9

@node Introduction, Lisp Data Types, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

  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}.

@menu
* Caveats::             Flaws and a request for help.
* Lisp History::        Emacs Lisp is descended from Maclisp.
* Conventions::         How the manual is formatted.

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.  @xref{Top,, Common Lisp Extension, cl, Common Lisp
Extensions}.

  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.

@example
(cons 'foo ())                ; @r{Emphasize the empty list}
(not nil)                     ; @r{Emphasize the truth value @var{false}}
@end example

@cindex @code{t} and truth
@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

@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.  The same is true of
any symbol whose name starts with a colon (@samp{:}).  @xref{Constant
Variables}.

@node Evaluation Notation
@subsection Evaluation Notation
@cindex evaluation notation
@cindex documentation 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{}}:

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.

@example
@group
(progn (print 'foo) (print 'bar))
     @print{} foo
     @print{} bar
     @result{} bar
@end group
@end example

  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
following argument name will have a value, as a variable, which is a
list of all these remaining arguments.  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},

@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 any
variable can be set by the user, certain variables that exist
specifically so that users can change them 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

@section Version Information

  These facilities provide information about which version of Emacs is
in use.

@deffn Command emacs-version
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

  @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

Called interactively, the function prints the same information in the
echo area.
@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

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.

88155:d7ddb3e565de

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004,
@c   2005 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

  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.

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.

@example
(cons 'foo ())                ; @r{Emphasize the empty list}
(not nil)                     ; @r{Emphasize the truth value @var{false}}
@end example

@cindex @code{t}, uses of
@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

@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}.

@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{}}:

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

  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},

@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

@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

  @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

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