annotate lispref/intro.texi @ 69524:1e827d428dd6

(ido-edit-input): Use selected match, if any.
author Kim F. Storm <storm@cua.dk>
date Thu, 16 Mar 2006 22:23:22 +0000
parents 067115a6e738
children 5565c9588f39 c5406394f567
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
64889
e836425ee789 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 63213
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004,
68648
067115a6e738 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 65328
diff changeset
4 @c 2005, 2006 Free Software Foundation, Inc.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/intro
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7
29256
9ff75c18dc0c *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28304
diff changeset
8 @node Introduction, Lisp Data Types, Top, Top
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @comment node-name, next, previous, up
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @chapter Introduction
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 Most of the GNU Emacs text editor is written in the programming
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 language called Emacs Lisp. You can write new code in Emacs Lisp and
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 install it as an extension to the editor. However, Emacs Lisp is more
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 than a mere ``extension language''; it is a full computer programming
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 language in its own right. You can use it as you would any other
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 programming language.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 Because Emacs Lisp is designed for use in an editor, it has special
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 features for scanning and parsing text as well as features for handling
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 files, buffers, displays, subprocesses, and so on. Emacs Lisp is
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 closely integrated with the editing facilities; thus, editing commands
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 are functions that can also conveniently be called from Lisp programs,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 and parameters for customization are ordinary Lisp variables.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
26 This manual attempts to be a full description of Emacs Lisp. For a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
27 beginner's introduction to Emacs Lisp, see @cite{An Introduction to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
28 Emacs Lisp Programming}, by Bob Chassell, also published by the Free
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
29 Software Foundation. This manual presumes considerable familiarity with
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
30 the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
31 basic information.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
32
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
33 Generally speaking, the earlier chapters describe features of Emacs
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
34 Lisp that have counterparts in many programming languages, and later
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
35 chapters describe features that are peculiar to Emacs Lisp or relate
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
36 specifically to editing.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37
63213
aec5bc9f2868 Don't set VERSION here a second time. Mention Emacs' version too.
Lute Kamstra <lute@gnu.org>
parents: 58497
diff changeset
38 This is edition @value{VERSION} of the GNU Emacs Lisp Reference
aec5bc9f2868 Don't set VERSION here a second time. Mention Emacs' version too.
Lute Kamstra <lute@gnu.org>
parents: 58497
diff changeset
39 Manual, corresponding to Emacs version @value{EMACSVER}.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 @menu
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 * Caveats:: Flaws and a request for help.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 * Lisp History:: Emacs Lisp is descended from Maclisp.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 * Conventions:: How the manual is formatted.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
45 * Version Info:: Which Emacs version is running?
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 * Acknowledgements:: The authors, editors, and sponsors of this manual.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 @end menu
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 @node Caveats
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 @section Caveats
40470
8154a8684502 Add index item.
Richard M. Stallman <rms@gnu.org>
parents: 39994
diff changeset
51 @cindex bugs in this manual
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 This manual has gone through numerous drafts. It is nearly complete
7114
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
54 but not flawless. There are a few topics that are not covered, either
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
55 because we consider them secondary (such as most of the individual
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
56 modes) or because they are yet to be written. Because we are not able
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
57 to deal with them completely, we have left out several parts
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
58 intentionally. This includes most information about usage on VMS.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 The manual should be fully correct in what it does cover, and it is
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 therefore open to criticism on anything it says---from specific examples
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 and descriptive text, to the ordering of chapters and sections. If
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 something is confusing, or you find that you have to look at the sources
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 or experiment to learn something not covered in the manual, then perhaps
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 the manual should be fixed. Please let us know.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @iftex
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
68 As you use this manual, we ask that you mark pages with corrections so
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
69 you can later look them up and send them to us. If you think of a simple,
7114
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
70 real-life example for a function or group of functions, please make an
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 effort to write it up and send it in. Please reference any comments to
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 the chapter name, section name, and function name, as appropriate, since
7114
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
73 page numbers and chapter and section numbers will change and we may have
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
74 trouble finding the text you are talking about. Also state the number
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
75 of the edition you are criticizing.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 @end iftex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 26288
diff changeset
77 @ifnottex
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 As you use this manual, we ask that you send corrections as soon as you
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 find them. If you think of a simple, real life example for a function
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81 or group of functions, please make an effort to write it up and send it
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 in. Please reference any comments to the node name and function or
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 variable name, as appropriate. Also state the number of the edition
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
84 you are criticizing.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 26288
diff changeset
85 @end ifnottex
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86
48019
ed648a134b7e Add index entries.
Richard M. Stallman <rms@gnu.org>
parents: 42826
diff changeset
87 @cindex bugs
ed648a134b7e Add index entries.
Richard M. Stallman <rms@gnu.org>
parents: 42826
diff changeset
88 @cindex suggestions
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 Please mail comments and corrections to
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @example
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
92 bug-lisp-manual@@gnu.org
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 @noindent
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 We let mail to this list accumulate unread until someone decides to
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 apply the corrections. Months, and sometimes years, go by between
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 updates. So please attach no significance to the lack of a reply---your
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 mail @emph{will} be acted on in due time. If you want to contact the
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 Emacs maintainers more quickly, send mail to
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
101 @code{bug-gnu-emacs@@gnu.org}.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 @node Lisp History
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @section Lisp History
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 @cindex Lisp history
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
107 Lisp (LISt Processing language) was first developed in the late 1950s
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 at the Massachusetts Institute of Technology for research in artificial
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
109 intelligence. The great power of the Lisp language makes it ideal
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 for other purposes as well, such as writing editing commands.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 @cindex Maclisp
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @cindex Common Lisp
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 Dozens of Lisp implementations have been built over the years, each
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 with its own idiosyncrasies. Many of them were inspired by Maclisp,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
116 which was written in the 1960s at MIT's Project MAC. Eventually the
7114
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
117 implementors of the descendants of Maclisp came together and developed a
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
118 standard for Lisp systems, called Common Lisp. In the meantime, Gerry
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
119 Sussman and Guy Steele at MIT developed a simplified but very powerful
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
120 dialect of Lisp, called Scheme.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 Lisp. If you know Common Lisp, you will notice many similarities.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
124 However, many features of Common Lisp have been omitted or
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 simplified in order to reduce the memory requirements of GNU Emacs.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 Sometimes the simplifications are so drastic that a Common Lisp user
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 might be very confused. We will occasionally point out how GNU Emacs
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 Lisp differs from Common Lisp. If you don't know Common Lisp, don't
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 worry about it; this manual is self-contained.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
131 @pindex cl
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
132 A certain amount of Common Lisp emulation is available via the
54394
897eca9a17ed (Lisp History): Replace xref to `cl' manual with inforef.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54377
diff changeset
133 @file{cl} library. @inforef{Top, Overview, cl}.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
134
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
135 Emacs Lisp is not at all influenced by Scheme; but the GNU project has
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
136 an implementation of Scheme, called Guile. We use Guile in all new GNU
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
137 software that calls for extensibility.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
138
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 @node Conventions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 @section Conventions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 This section explains the notational conventions that are used in this
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 manual. You may want to skip this section and refer back to it later.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 @menu
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 * Some Terms:: Explanation of terms we use in this manual.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 * nil and t:: How the symbols @code{nil} and @code{t} are used.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 * Evaluation Notation:: The format we use for examples of evaluation.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
149 * Printing Notation:: The format we use when examples print text.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 * Error Messages:: The format we use for examples of errors.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 * Buffer Text Notation:: The format we use for buffer contents in examples.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 * Format of Descriptions:: Notation for describing functions, variables, etc.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 @end menu
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 @node Some Terms
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @subsection Some Terms
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
159 printer'' refer to those routines in Lisp that convert textual
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
160 representations of Lisp objects into actual Lisp objects, and vice
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 versa. @xref{Printed Representation}, for more details. You, the
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 person reading this manual, are thought of as ``the programmer'' and are
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
163 addressed as ``you''. ``The user'' is the person who uses Lisp
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
164 programs, including those you write.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 @cindex fonts
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
167 Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
168 Names that represent metasyntactic variables, or arguments to a function
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
169 being described, are formatted like this: @var{first-number}.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 @node nil and t
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @subsection @code{nil} and @code{t}
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @cindex @code{nil}, uses of
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @cindex truth value
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @cindex boolean
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @cindex false
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7114
diff changeset
178 In Lisp, the symbol @code{nil} has three separate meanings: it
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 is a symbol with the name @samp{nil}; it is the logical truth value
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 @var{false}; and it is the empty list---the list of zero elements.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 When used as a variable, @code{nil} always has the value @code{nil}.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 identical: they stand for the same object, the symbol @code{nil}. The
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 different ways of writing the symbol are intended entirely for human
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 readers. After the Lisp reader has read either @samp{()} or @samp{nil},
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 there is no way to determine which representation was actually written
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 by the programmer.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 In this manual, we use @code{()} when we wish to emphasize that it
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 means the empty list, and we use @code{nil} when we wish to emphasize
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 that it means the truth value @var{false}. That is a good convention to use
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 in Lisp programs also.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 (cons 'foo ()) ; @r{Emphasize the empty list}
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 (not nil) ; @r{Emphasize the truth value @var{false}}
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199
65328
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
200 @cindex @code{t}, uses of
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @cindex true
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 In contexts where a truth value is expected, any non-@code{nil} value
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 is considered to be @var{true}. However, @code{t} is the preferred way
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 to represent the truth value @var{true}. When you need to choose a
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 value which represents @var{true}, and there is no other basis for
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
206 choosing, use @code{t}. The symbol @code{t} always has the value
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
207 @code{t}.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 evaluate to themselves. This is so that you do not need to quote them
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 to use them as constants in a program. An attempt to change their
65328
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
212 values results in a @code{setting-constant} error. @xref{Constant
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 Variables}.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 @node Evaluation Notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 @subsection Evaluation Notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 @cindex evaluation notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 @cindex documentation notation
65328
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
219 @cindex notation
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 A Lisp expression that you can evaluate is called a @dfn{form}.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 Evaluating a form always produces a result, which is a Lisp object. In
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 the examples in this manual, this is indicated with @samp{@result{}}:
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 (car '(1 2))
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @result{} 1
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @noindent
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 You can read this as ``@code{(car '(1 2))} evaluates to 1''.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 When a form is a macro call, it expands into a new form for Lisp to
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 evaluate. We show the result of the expansion with
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
235 @samp{@expansion{}}. We may or may not show the result of the
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 evaluation of the expanded form.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 (third '(a b c))
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 @expansion{} (car (cdr (cdr '(a b c))))
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 @result{} c
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243
7114
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
244 Sometimes to help describe one form we show another form that
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 produces identical results. The exact equivalence of two forms is
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 indicated with @samp{@equiv{}}.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 (make-sparse-keymap) @equiv{} (list 'keymap)
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @node Printing Notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 @subsection Printing Notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @cindex printing notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 Many of the examples in this manual print text when they are
7114
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
257 evaluated. If you execute example code in a Lisp Interaction buffer
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
258 (such as the buffer @samp{*scratch*}), the printed text is inserted into
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
259 the buffer. If you execute the example by other means (such as by
31cb9f9b9784 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6453
diff changeset
260 evaluating the function @code{eval-region}), the printed text is
26288
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
261 displayed in the echo area.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 Examples in this manual indicate printed text with @samp{@print{}},
58384
3171059923a2 (Printing Notation): Avoid confusion of `print' when explaining @print.
Richard M. Stallman <rms@gnu.org>
parents: 54394
diff changeset
264 irrespective of where that text goes. The value returned by
3171059923a2 (Printing Notation): Avoid confusion of `print' when explaining @print.
Richard M. Stallman <rms@gnu.org>
parents: 54394
diff changeset
265 evaluating the form (here @code{bar}) follows on a separate line with
3171059923a2 (Printing Notation): Avoid confusion of `print' when explaining @print.
Richard M. Stallman <rms@gnu.org>
parents: 54394
diff changeset
266 @samp{@result{}}.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 @group
58497
39adaa8660ab (Printing Notation): Fix previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58384
diff changeset
270 (progn (prin1 'foo) (princ "\n") (prin1 'bar))
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 @print{} foo
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 @print{} bar
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 @result{} bar
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 @end group
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 @node Error Messages
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @subsection Error Messages
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 @cindex error message notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 Some examples signal errors. This normally displays an error message
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 in the echo area. We show the error message on a line starting with
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 @samp{@error{}}. Note that @samp{@error{}} itself does not appear in
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 the echo area.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 (+ 23 'x)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
288 @error{} Wrong type argument: number-or-marker-p, x
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 @node Buffer Text Notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @subsection Buffer Text Notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 @cindex buffer text notation
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
295 Some examples describe modifications to the contents of a buffer, by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
296 showing the ``before'' and ``after'' versions of the text. These
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
297 examples show the contents of the buffer in question between two lines
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
298 of dashes containing the buffer name. In addition, @samp{@point{}}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
299 indicates the location of point. (The symbol for point, of course, is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
300 not part of the text in the buffer; it indicates the place
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
301 @emph{between} two characters where point is currently located.)
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 ---------- Buffer: foo ----------
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 This is the @point{}contents of foo.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 ---------- Buffer: foo ----------
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 (insert "changed ")
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @result{} nil
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 ---------- Buffer: foo ----------
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 This is the changed @point{}contents of foo.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 ---------- Buffer: foo ----------
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @node Format of Descriptions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @subsection Format of Descriptions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @cindex description format
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 Functions, variables, macros, commands, user options, and special
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 forms are described in this manual in a uniform format. The first
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 line of a description contains the name of the item followed by its
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 arguments, if any.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 26288
diff changeset
323 @ifnottex
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 The category---function, variable, or whatever---appears at the
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 beginning of the line.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 26288
diff changeset
326 @end ifnottex
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @iftex
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 The category---function, variable, or whatever---is printed next to the
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 right margin.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 @end iftex
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 The description follows on succeeding lines, sometimes with examples.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 @menu
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 * A Sample Function Description:: A description of an imaginary
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 function, @code{foo}.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 * A Sample Variable Description:: A description of an imaginary
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 variable,
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48019
diff changeset
338 @code{electric-future-map}.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 @end menu
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @node A Sample Function Description
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 @subsubsection A Sample Function Description
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @cindex function descriptions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 @cindex command descriptions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 @cindex macro descriptions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 @cindex special form descriptions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 In a function description, the name of the function being described
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
349 appears first. It is followed on the same line by a list of argument
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
350 names. These names are also used in the body of the description, to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
351 stand for the values of the arguments.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
353 The appearance of the keyword @code{&optional} in the argument list
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
354 indicates that the subsequent arguments may be omitted (omitted
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
355 arguments default to @code{nil}). Do not write @code{&optional} when
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
356 you call the function.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357
65328
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
358 The keyword @code{&rest} (which must be followed by a single
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
359 argument name) indicates that any number of arguments can follow. The
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
360 single argument name following @code{&rest} will receive, as its
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
361 value, a list of all the remaining arguments passed to the function.
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
362 Do not write @code{&rest} when you call the function.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 Here is a description of an imaginary function @code{foo}:
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @defun foo integer1 &optional integer2 &rest integers
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 The function @code{foo} subtracts @var{integer1} from @var{integer2},
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 then adds all the rest of the arguments to the result. If @var{integer2}
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 is not supplied, then the number 19 is used by default.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 (foo 1 5 3 9)
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 @result{} 16
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 (foo 5)
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 @result{} 14
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
378 @need 1500
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 More generally,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 (foo @var{w} @var{x} @var{y}@dots{})
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 @equiv{}
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 (+ (- @var{x} @var{w}) @var{y}@dots{})
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 @end defun
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
388 Any argument whose name contains the name of a type (e.g.,
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 type. A plural of a type (such as @var{buffers}) often means a list of
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
391 objects of that type. Arguments named @var{object} may be of any type.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
392 (@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
393 with other sorts of names (e.g., @var{new-file}) are discussed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
394 specifically in the description of the function. In some sections,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
395 features common to the arguments of several functions are described at
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
396 the beginning.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 @xref{Lambda Expressions}, for a more complete description of optional
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 and rest arguments.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 Command, macro, and special form descriptions have the same format,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 but the word `Function' is replaced by `Command', `Macro', or `Special
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 Form', respectively. Commands are simply functions that may be called
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 interactively; macros process their arguments differently from functions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 (the arguments are not evaluated), but are presented the same way.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 Special form descriptions use a more complex notation to specify
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
408 optional and repeated arguments because they can break the argument
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 list down into separate arguments in more complicated ways.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
410 @samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 arguments. Parentheses are used when several arguments are grouped into
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 additional levels of list structure. Here is an example:
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 This imaginary special form implements a loop that executes the
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 @var{body} forms and then increments the variable @var{var} on each
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 iteration. On the first iteration, the variable has the value
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
419 @var{from}; on subsequent iterations, it is incremented by one (or by
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 @var{inc} if that is given). The loop exits before executing @var{body}
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 if @var{var} equals @var{to}. Here is an example:
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 (count-loop (i 0 10)
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 (prin1 i) (princ " ")
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
426 (prin1 (aref vector i))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
427 (terpri))
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
430 If @var{from} and @var{to} are omitted, @var{var} is bound to
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @code{nil} before the loop begins, and the loop exits if @var{var} is
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 non-@code{nil} at the beginning of an iteration. Here is an example:
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 @example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 (count-loop (done)
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 (if (pending)
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 (fixit)
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 (setq done t)))
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 @end example
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 In this special form, the arguments @var{from} and @var{to} are
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 optional, but must both be present or both absent. If they are present,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @var{inc} may optionally be specified as well. These arguments are
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 grouped with the argument @var{var} into a list, to distinguish them
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 from @var{body}, which includes all remaining elements of the form.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @end defspec
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 @node A Sample Variable Description
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @subsubsection A Sample Variable Description
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @cindex variable descriptions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @cindex option descriptions
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452
65328
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
453 A @dfn{variable} is a name that can hold a value. Although nearly
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
454 all variables can be set by the user, certain variables exist
5e93eb177fdb (nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
455 specifically so that users can change them; these are called @dfn{user
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 options}. Ordinary variables and user options are described using a
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 format like that for functions except that there are no arguments.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 Here is a description of the imaginary @code{electric-future-map}
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 variable.@refill
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @defvar electric-future-map
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 The value of this variable is a full keymap used by Electric Command
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 Future mode. The functions in this map allow you to edit commands you
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 have not yet thought about executing.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @end defvar
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 User option descriptions have the same format, but `Variable' is
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 replaced by `User Option'.
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
471 @node Version Info
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
472 @section Version Information
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
473
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
474 These facilities provide information about which version of Emacs is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
475 in use.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
476
54377
a9843a971cfc (Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
477 @deffn Command emacs-version &optional here
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
478 This function returns a string describing the version of Emacs that is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
479 running. It is useful to include this string in bug reports.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
480
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
481 @smallexample
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
482 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
483 (emacs-version)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
484 @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
485 of Sat Feb 14 1998 on psilocin.gnu.org"
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
486 @end group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
487 @end smallexample
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
488
54377
a9843a971cfc (Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
489 If @var{here} is non-@code{nil}, it inserts the text in the buffer
a9843a971cfc (Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
490 before point, and returns @code{nil}. Called interactively, the
a9843a971cfc (Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
491 function prints the same information in the echo area, but giving a
a9843a971cfc (Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
492 prefix argument makes @var{here} non-@code{nil}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
493 @end deffn
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
494
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
495 @defvar emacs-build-time
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
496 The value of this variable indicates the time at which Emacs was built
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
497 at the local site. It is a list of three integers, like the value
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
498 of @code{current-time} (@pxref{Time of Day}).
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
499
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
500 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
501 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
502 emacs-build-time
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
503 @result{} (13623 62065 344633)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
504 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
505 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
506 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
507
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
508 @defvar emacs-version
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
509 The value of this variable is the version of Emacs being run. It is a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
510 string such as @code{"20.3.1"}. The last number in this string is not
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
511 really part of the Emacs release version number; it is incremented each
36986
a206784e7db9 Minor fix.
Richard M. Stallman <rms@gnu.org>
parents: 29256
diff changeset
512 time you build Emacs in any given directory. A value with four numeric
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
513 components, such as @code{"20.3.9.1"}, indicates an unreleased test
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22366
diff changeset
514 version.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
515 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
516
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
517 The following two variables have existed since Emacs version 19.23:
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
518
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
519 @defvar emacs-major-version
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
520 The major version number of Emacs, as an integer. For Emacs version
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
521 20.3, the value is 20.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
522 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
523
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
524 @defvar emacs-minor-version
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
525 The minor version number of Emacs, as an integer. For Emacs version
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
526 20.3, the value is 3.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
527 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
528
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 @node Acknowledgements
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 @section Acknowledgements
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 Richard M. Stallman and Chris Welty, the volunteers of the GNU manual
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 group, in an effort extending over several years. Robert J. Chassell
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 helped to review and edit the manual, with the support of the Defense
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
537 A. Hunt, Jr.@: of Computational Logic, Inc.
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
548 Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp,
6453
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty,
974a37e5c414 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 Dale Worley, Rusty Wright, and David D. Zuhn.
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
551
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
552 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
553 arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
554 @end ignore