annotate lispref/intro.texi @ 57972:fc790bd5db8f

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