More small edits for doc/lispref
* control.texi: Where possible, use example rather than smallexample. (Sequencing, Conditionals, Signaling Errors, Handling Errors): Tweak page breaks. * customize.texi: Where possible, use example rather than smallexample. (Common Keywords, Variable Definitions, Applying Customizations) (Custom Themes): Tweak page breaks. * eval.texi, functions.texi, loading.texi, macros.texi: Where possible, use example rather than smallexample. * sequences.texi (Arrays): Tweak page breaks. * symbols.texi: Where possible, use example rather than smallexample. (Symbol Components): Fix typo. (Other Plists): Tweak page break.
This commit is contained in:
Glenn Morris
parent
9824f50523
commit
ddff335186
9 changed files with 161 additions and 147 deletions
|
|
@ -1,3 +1,22 @@
|
|||
2012-05-05 Glenn Morris <rgm@gnu.org>
|
||||
|
||||
* eval.texi, functions.texi, loading.texi, macros.texi:
|
||||
Where possible, use example rather than smallexample.
|
||||
|
||||
* symbols.texi: Where possible, use example rather than smallexample.
|
||||
(Symbol Components): Fix typo.
|
||||
(Other Plists): Tweak page break.
|
||||
|
||||
* sequences.texi (Arrays): Tweak page breaks.
|
||||
|
||||
* customize.texi: Where possible, use example rather than smallexample.
|
||||
(Common Keywords, Variable Definitions, Applying Customizations)
|
||||
(Custom Themes): Tweak page breaks.
|
||||
|
||||
* control.texi: Where possible, use example rather than smallexample.
|
||||
(Sequencing, Conditionals, Signaling Errors, Handling Errors):
|
||||
Tweak page breaks.
|
||||
|
||||
2012-05-04 Glenn Morris <rgm@gnu.org>
|
||||
|
||||
* lists.texi (List-related Predicates, List Variables):
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Emacs Lisp Reference Manual.
|
||||
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
|
||||
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
|
||||
@c See the file elisp.texi for copying conditions.
|
||||
@setfilename ../../info/control
|
||||
@node Control Structures, Variables, Evaluation, Top
|
||||
|
|
@ -94,8 +94,8 @@ order, returning the result of the final form.
|
|||
@end example
|
||||
@end defspec
|
||||
|
||||
Two other control constructs likewise evaluate a series of forms but return
|
||||
a different value:
|
||||
Two other constructs likewise evaluate a series of forms but return
|
||||
different values:
|
||||
|
||||
@defspec prog1 form1 forms@dots{}
|
||||
This special form evaluates @var{form1} and all of the @var{forms}, in
|
||||
|
|
@ -160,8 +160,8 @@ If @var{condition} has the value @code{nil}, and no @var{else-forms} are
|
|||
given, @code{if} returns @code{nil}.
|
||||
|
||||
@code{if} is a special form because the branch that is not selected is
|
||||
never evaluated---it is ignored. Thus, in the example below,
|
||||
@code{true} is not printed because @code{print} is never called.
|
||||
never evaluated---it is ignored. Thus, in this example,
|
||||
@code{true} is not printed because @code{print} is never called:
|
||||
|
||||
@example
|
||||
@group
|
||||
|
|
@ -258,9 +258,7 @@ clauses was successful. To do this, we use @code{t} as the
|
|||
@var{condition} of the last clause, like this: @code{(t
|
||||
@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is
|
||||
never @code{nil}, so this clause never fails, provided the @code{cond}
|
||||
gets to it at all.
|
||||
|
||||
For example,
|
||||
gets to it at all. For example:
|
||||
|
||||
@example
|
||||
@group
|
||||
|
|
@ -812,10 +810,10 @@ handlers that handle the error: @code{condition-case} binds a local
|
|||
variable to a list of the form @code{(@var{error-symbol} .@:
|
||||
@var{data})} (@pxref{Handling Errors}).
|
||||
|
||||
The function @code{signal} never returns (though in older Emacs versions
|
||||
it could sometimes return).
|
||||
The function @code{signal} never returns.
|
||||
@c (though in older Emacs versions it sometimes could).
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(signal 'wrong-number-of-arguments '(x y))
|
||||
@error{} Wrong number of arguments: x, y
|
||||
|
|
@ -825,7 +823,7 @@ it could sometimes return).
|
|||
(signal 'no-such-error '("My unknown error condition"))
|
||||
@error{} peculiar error: "My unknown error condition"
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@cindex CL note---no continuable errors
|
||||
|
|
@ -991,7 +989,7 @@ to allow the debugger to run before the handler); @var{body} is one or more
|
|||
Lisp expressions to be executed when this handler handles an error.
|
||||
Here are examples of handlers:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(error nil)
|
||||
|
||||
|
|
@ -1001,7 +999,7 @@ Here are examples of handlers:
|
|||
(message
|
||||
"Either division by zero or failure to open a file"))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Each error that occurs has an @dfn{error symbol} that describes what
|
||||
kind of error it is. The @code{error-conditions} property of this
|
||||
|
|
@ -1034,9 +1032,9 @@ Sometimes it is necessary to re-throw a signal caught by
|
|||
@code{condition-case}, for some outer-level handler to catch. Here's
|
||||
how to do that:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(signal (car err) (cdr err))
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
where @code{err} is the error description variable, the first argument
|
||||
|
|
@ -1055,7 +1053,7 @@ Here is an example of using @code{condition-case} to handle the error
|
|||
that results from dividing by zero. The handler displays the error
|
||||
message (but without a beep), then returns a very large number.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(defun safe-divide (dividend divisor)
|
||||
(condition-case err
|
||||
|
|
@ -1076,22 +1074,24 @@ message (but without a beep), then returns a very large number.
|
|||
@print{} Arithmetic error: (arith-error)
|
||||
@result{} 1000000
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this @code{condition-case}. Thus,
|
||||
The handler specifies condition name @code{arith-error} so that it
|
||||
will handle only division-by-zero errors. Other kinds of errors will
|
||||
not be handled (by this @code{condition-case}). Thus:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(safe-divide nil 3)
|
||||
@error{} Wrong type argument: number-or-marker-p, nil
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Here is a @code{condition-case} that catches all kinds of errors,
|
||||
including those signaled with @code{error}:
|
||||
including those from @code{error}:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(setq baz 34)
|
||||
@result{} 34
|
||||
|
|
@ -1109,7 +1109,7 @@ including those signaled with @code{error}:
|
|||
@print{} The error was: (error "Rats! The variable baz was 34, not 35")
|
||||
@result{} 2
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@defmac ignore-errors body@dots{}
|
||||
This construct executes @var{body}, ignoring any errors that occur
|
||||
|
|
@ -1120,12 +1120,12 @@ otherwise, it returns @code{nil}.
|
|||
Here's the example at the beginning of this subsection rewritten using
|
||||
@code{ignore-errors}:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(ignore-errors
|
||||
(delete-file filename))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defmac
|
||||
|
||||
@defmac with-demoted-errors body@dots{}
|
||||
|
|
@ -1280,7 +1280,7 @@ Variables}).
|
|||
For example, here we make an invisible buffer for temporary use, and
|
||||
make sure to kill it before finishing:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(let ((buffer (get-buffer-create " *temp*")))
|
||||
(with-current-buffer buffer
|
||||
|
|
@ -1288,7 +1288,7 @@ make sure to kill it before finishing:
|
|||
@var{body-form}
|
||||
(kill-buffer buffer))))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
You might think that we could just as well write @code{(kill-buffer
|
||||
|
|
@ -1313,7 +1313,7 @@ is protected with a form that guarantees deletion of the process in the
|
|||
event of failure. Otherwise, Emacs might fill up with useless
|
||||
subprocesses.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(let ((win nil))
|
||||
(unwind-protect
|
||||
|
|
@ -1324,7 +1324,7 @@ subprocesses.
|
|||
(error "Ftp login failed")))
|
||||
(or win (and process (delete-process process)))))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
This example has a small bug: if the user types @kbd{C-g} to
|
||||
quit, and the quit happens immediately after the function
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Emacs Lisp Reference Manual.
|
||||
@c Copyright (C) 1997-2012 Free Software Foundation, Inc.
|
||||
@c Copyright (C) 1997-2012 Free Software Foundation, Inc.
|
||||
@c See the file elisp.texi for copying conditions.
|
||||
@setfilename ../../info/customize
|
||||
@node Customization, Loading, Macros, Top
|
||||
|
|
@ -158,7 +158,7 @@ Packages distributed as part of Emacs that use the
|
|||
@defvar customize-package-emacs-version-alist
|
||||
This alist provides a mapping for the versions of Emacs that are
|
||||
associated with versions of a package listed in the
|
||||
@code{:package-version} keyword. Its elements look like this:
|
||||
@code{:package-version} keyword. Its elements are:
|
||||
|
||||
@example
|
||||
(@var{package} (@var{pversion} . @var{eversion})@dots{})
|
||||
|
|
@ -169,6 +169,8 @@ elements that contain a package version @var{pversion} with an
|
|||
associated Emacs version @var{eversion}. These versions are strings.
|
||||
For example, the MH-E package updates this alist with the following:
|
||||
|
||||
@c Must be small else too wide.
|
||||
@c FIXME obviously this is out of date (in the code).
|
||||
@smallexample
|
||||
(add-to-list 'customize-package-emacs-version-alist
|
||||
'(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
|
||||
|
|
@ -395,7 +397,7 @@ Set the variable's @code{safe-local-variable} property to
|
|||
@item :set-after @var{variables}
|
||||
@kindex set-after@r{, @code{defcustom} keyword}
|
||||
When setting variables according to saved customizations, make sure to
|
||||
set the variables @var{variables} before this one; in other words, delay
|
||||
set the variables @var{variables} before this one; i.e., delay
|
||||
setting this variable until after those others have been handled. Use
|
||||
@code{:set-after} if setting this variable won't work properly unless
|
||||
those other variables already have their intended values.
|
||||
|
|
@ -682,9 +684,9 @@ The argument to the @code{:options} keywords should be a list of
|
|||
specifications for reasonable keys in the alist. Ordinarily, they are
|
||||
simply atoms, which stand for themselves. For example:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
:options '("foo" "bar" "baz")
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
specifies that there are three ``known'' keys, namely @code{"foo"},
|
||||
|
|
@ -696,9 +698,9 @@ integer. You can specify this by using a list instead of an atom in
|
|||
the list. The first element will specify the key, like before, while
|
||||
the second element will specify the value type. For example:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
:options '("foo" ("bar" integer) "baz")
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Finally, you may want to change how the key is presented. By default,
|
||||
the key is simply shown as a @code{const}, since the user cannot change
|
||||
|
|
@ -708,37 +710,37 @@ you may want to use a more specialized type for presenting the key, like
|
|||
This is done by using a customization type specification instead of a
|
||||
symbol for the key.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
:options '("foo" ((function-item some-function) integer)
|
||||
"baz")
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Many alists use lists with two elements, instead of cons cells. For
|
||||
example,
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
|
||||
"Each element is a list of the form (KEY VALUE).")
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
instead of
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
|
||||
"Each element is a cons-cell (KEY . VALUE).")
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Because of the way lists are implemented on top of cons cells, you can
|
||||
treat @code{list-alist} in the example above as a cons cell alist, where
|
||||
the value type is a list with a single element containing the real
|
||||
value.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
|
||||
"Each element is a list of the form (KEY VALUE)."
|
||||
:type '(alist :value-type (group integer)))
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
The @code{group} widget is used here instead of @code{list} only because
|
||||
the formatting is better suited for the purpose.
|
||||
|
|
@ -746,14 +748,14 @@ the formatting is better suited for the purpose.
|
|||
Similarly, you can have alists with more values associated with each
|
||||
key, using variations of this trick:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(defcustom person-data '(("brian" 50 t)
|
||||
("dorith" 55 nil)
|
||||
("ken" 52 t))
|
||||
"Alist of basic info about people.
|
||||
Each element has the form (NAME AGE MALE-FLAG)."
|
||||
:type '(alist :value-type (group integer boolean)))
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@item (plist :key-type @var{key-type} :value-type @var{value-type})
|
||||
This customization type is similar to @code{alist} (see above), except
|
||||
|
|
@ -1264,7 +1266,7 @@ customization settings for variables and faces, respectively. When
|
|||
the user invokes @samp{Save for future sessions} in the Customize
|
||||
interface, that takes effect by writing a @code{custom-set-variables}
|
||||
and/or a @code{custom-set-faces} form into the custom file, to be
|
||||
evaluated the next time Emacs starts up.
|
||||
evaluated the next time Emacs starts.
|
||||
|
||||
@defun custom-set-variables &rest args
|
||||
This function installs the variable customizations specified by
|
||||
|
|
@ -1335,11 +1337,10 @@ the theme; this is the description shown when the user invokes the
|
|||
@code{describe-theme} command or types @kbd{?} in the @samp{*Custom
|
||||
Themes*} buffer.
|
||||
|
||||
Two special theme names are disallowed: @code{user} is a ``dummy''
|
||||
theme which stores the user's direct customization settings, and
|
||||
@code{changed} is a ``dummy'' theme which stores changes made outside
|
||||
of the Customize system. If you specify either of these as the
|
||||
@var{theme} argument, @code{deftheme} signals an error.
|
||||
Two special theme names are disallowed (using them causes an error):
|
||||
@code{user} is a ``dummy'' theme that stores the user's direct
|
||||
customization settings, and @code{changed} is a ``dummy'' theme that
|
||||
stores changes made outside of the Customize system.
|
||||
@end defmac
|
||||
|
||||
@defmac provide-theme theme
|
||||
|
|
@ -1387,7 +1388,7 @@ displays the source file and asks for confirmation from the user
|
|||
before loading any non-built-in theme for the first time.
|
||||
|
||||
The following functions are useful for programmatically enabling and
|
||||
disabling Custom themes:
|
||||
disabling themes:
|
||||
|
||||
@defun custom-theme-p theme
|
||||
This function return a non-@code{nil} value if @var{theme} (a symbol)
|
||||
|
|
@ -1400,14 +1401,11 @@ it returns @code{nil}.
|
|||
This function loads the Custom theme named @var{theme} from its source
|
||||
file, looking for the source file in the directories specified by the
|
||||
variable @code{custom-theme-load-path}. @xref{Custom Themes,,, emacs,
|
||||
The GNU Emacs Manual}. It also @dfn{enables} the theme, causing its
|
||||
variable and face settings to take effect.
|
||||
|
||||
If the optional argument @var{no-confirm} is non-@code{nil}, this
|
||||
skips prompting the user for confirmation before loading the theme.
|
||||
|
||||
If the optional argument @var{no-enable} is non-@code{nil}, the theme
|
||||
is loaded but not enabled.
|
||||
The GNU Emacs Manual}. It also @dfn{enables} the theme (unless the
|
||||
optional argument @var{no-enable} is non-@code{nil}), causing its
|
||||
variable and face settings to take effect. It prompts the user for
|
||||
confirmation before loading the theme, unless the optional argument
|
||||
@var{no-confirm} is non-@code{nil}.
|
||||
@end deffn
|
||||
|
||||
@deffn Command enable-theme theme
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Emacs Lisp Reference Manual.
|
||||
@c Copyright (C) 1990-1994, 1998, 2001-2012 Free Software Foundation, Inc.
|
||||
@c Copyright (C) 1990-1994, 1998, 2001-2012 Free Software Foundation, Inc.
|
||||
@c See the file elisp.texi for copying conditions.
|
||||
@setfilename ../../info/eval
|
||||
@node Evaluation, Control Structures, Symbols, Top
|
||||
|
|
@ -261,16 +261,13 @@ use @code{fset} to set the function cell of a symbol and
|
|||
into the function cell of @code{first}, and the symbol @code{first} into
|
||||
the function cell of @code{erste}.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
;; @r{Build this function cell linkage:}
|
||||
;; ------------- ----- ------- -------
|
||||
;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
|
||||
;; ------------- ----- ------- -------
|
||||
@end group
|
||||
@end smallexample
|
||||
|
||||
@smallexample
|
||||
@group
|
||||
(symbol-function 'car)
|
||||
@result{} #<subr car>
|
||||
|
|
@ -287,19 +284,19 @@ the function cell of @code{erste}.
|
|||
(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
|
||||
@result{} 1
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
By contrast, the following example calls a function without any symbol
|
||||
function indirection, because the first element is an anonymous Lisp
|
||||
function, not a symbol.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
((lambda (arg) (erste arg))
|
||||
'(1 2 3))
|
||||
@result{} 1
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
Executing the function itself evaluates its body; this does involve
|
||||
|
|
@ -308,18 +305,18 @@ symbol function indirection when calling @code{erste}.
|
|||
This form is rarely used and is now deprecated. Instead, you should write it
|
||||
as:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(funcall (lambda (arg) (erste arg))
|
||||
'(1 2 3))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
or just
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(let ((arg '(1 2 3))) (erste arg))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
The built-in function @code{indirect-function} provides an easy way to
|
||||
perform symbol function indirection explicitly.
|
||||
|
|
@ -342,12 +339,12 @@ loop in the chain of symbols.
|
|||
|
||||
Here is how you could define @code{indirect-function} in Lisp:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(defun indirect-function (function)
|
||||
(if (symbolp function)
|
||||
(indirect-function (symbol-function function))
|
||||
function))
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@node Function Forms
|
||||
|
|
|
|||
|
|
@ -398,7 +398,7 @@ after a @code{&rest} argument.
|
|||
|
||||
Here are some examples of argument lists and proper calls:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(funcall (lambda (n) (1+ n)) ; @r{One required:}
|
||||
1) ; @r{requires exactly one argument.}
|
||||
@result{} 2
|
||||
|
|
@ -410,7 +410,7 @@ after a @code{&rest} argument.
|
|||
(+ n (apply '+ ns))) ; @r{1 or more arguments.}
|
||||
1 2 3 4 5)
|
||||
@result{} 15
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@node Function Documentation
|
||||
@subsection Documentation Strings of Functions
|
||||
|
|
@ -821,7 +821,7 @@ char-table; that is, a list, a vector, a bool-vector, or a string. The
|
|||
result is always a list. The length of the result is the same as the
|
||||
length of @var{sequence}. For example:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(mapcar 'car '((a b) (c d) (e f)))
|
||||
@result{} (a c e)
|
||||
|
|
@ -853,7 +853,7 @@ Return the list of results."
|
|||
(mapcar* 'cons '(a b c) '(1 2 3 4))
|
||||
@result{} ((a . 1) (b . 2) (c . 3))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@defun mapc function sequence
|
||||
|
|
@ -874,7 +874,7 @@ argument and return a string. The argument @var{sequence} can be any
|
|||
kind of sequence except a char-table; that is, a list, a vector, a
|
||||
bool-vector, or a string.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(mapconcat 'symbol-name
|
||||
'(The cat in the hat)
|
||||
|
|
@ -888,7 +888,7 @@ bool-vector, or a string.
|
|||
"")
|
||||
@result{} "IBM.9111"
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@node Anonymous Functions
|
||||
|
|
@ -1189,18 +1189,18 @@ still allow the code to be byte compiled).
|
|||
For instance, in old versions of Emacs the @code{sit-for} function
|
||||
accepted three arguments, like this
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(sit-for seconds milliseconds nodisp)
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
However, calling @code{sit-for} this way is considered obsolete
|
||||
(@pxref{Waiting}). The old calling convention is deprecated like
|
||||
this:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(set-advertised-calling-convention
|
||||
'sit-for '(seconds &optional nodisp))
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@node Inline Functions
|
||||
|
|
@ -1260,11 +1260,11 @@ indicates a real problem, but usually the functions in question are
|
|||
defined in other files which would be loaded if that code is run. For
|
||||
example, byte-compiling @file{fortran.el} used to warn:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
In end of data:
|
||||
fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
|
||||
to be defined.
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
In fact, @code{gud-find-c-expr} is only used in the function that
|
||||
Fortran mode uses for the local value of
|
||||
|
|
@ -1277,9 +1277,9 @@ visible. You do that with @code{declare-function}.
|
|||
All you need to do is add a @code{declare-function} statement before the
|
||||
first use of the function in question:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(declare-function gud-find-c-expr "gud.el" nil)
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
|
||||
@samp{.el} can be omitted). The compiler takes for granted that that file
|
||||
|
|
|
|||
|
|
@ -251,31 +251,31 @@ for @code{PATH}; directory names are separated by @samp{:} (or
|
|||
current default directory. Here is an example of how to set
|
||||
@env{EMACSLOADPATH} variable from @command{sh}:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
export EMACSLOADPATH
|
||||
EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
Here is how to set it from @code{csh}:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
|
||||
initializes @code{load-path} with the following two directories:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
"/usr/local/share/emacs/@var{version}/site-lisp"
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
and
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
"/usr/local/share/emacs/site-lisp"
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
The first one is for locally installed packages for a particular Emacs
|
||||
|
|
@ -304,9 +304,9 @@ packages are installed, if any (@pxref{Packaging Basics}).
|
|||
It is common to add code to one's init file (@pxref{Init File}) to
|
||||
add one or more directories to @code{load-path}. For example:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(push "~/.emacs.d/lisp" load-path)
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Dumping Emacs uses a special value of @code{load-path}. If the
|
||||
value of @code{load-path} at the end of dumping is unchanged (that is,
|
||||
|
|
@ -340,9 +340,9 @@ similarly-named file in a directory earlier on @code{load-path}.
|
|||
|
||||
For instance, suppose @code{load-path} is set to
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
and that both these directories contain a file named @file{foo.el}.
|
||||
|
|
@ -535,24 +535,24 @@ it is executed while building Emacs.
|
|||
The following example shows how @code{doctor} is prepared for
|
||||
autoloading with a magic comment:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
;;;###autoload
|
||||
(defun doctor ()
|
||||
"Switch to *doctor* buffer and start giving psychotherapy."
|
||||
(interactive)
|
||||
(switch-to-buffer "*doctor*")
|
||||
(doctor-mode))
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
Here's what that produces in @file{loaddefs.el}:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(autoload (quote doctor) "doctor" "\
|
||||
Switch to *doctor* buffer and start giving psychotherapy.
|
||||
|
||||
\(fn)" t nil)
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
@cindex @code{fn} in function's documentation string
|
||||
|
|
@ -571,11 +571,11 @@ ordinary magic autoload comment would copy the whole definition into
|
|||
@code{loaddefs.el}. That is not desirable. You can put the desired
|
||||
@code{autoload} call into @code{loaddefs.el} instead by writing this:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
;;;###autoload (autoload 'foo "myfile")
|
||||
(mydefunmacro foo
|
||||
...)
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
You can use a non-default string as the autoload cookie and have the
|
||||
corresponding autoload calls written into a file whose name is
|
||||
|
|
@ -680,7 +680,7 @@ file should call @code{provide} at the top level to add the feature to
|
|||
For example, in @file{idlwave.el}, the definition for
|
||||
@code{idlwave-complete-filename} includes the following code:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(defun idlwave-complete-filename ()
|
||||
"Use the comint stuff to complete a file name."
|
||||
(require 'comint)
|
||||
|
|
@ -688,7 +688,7 @@ file should call @code{provide} at the top level to add the feature to
|
|||
(comint-completion-addsuffix nil)
|
||||
...)
|
||||
(comint-dynamic-complete-filename)))
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
The expression @code{(require 'comint)} loads the file @file{comint.el}
|
||||
|
|
@ -703,9 +703,9 @@ after the let exits.)
|
|||
|
||||
The @file{comint.el} file contains the following top-level expression:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(provide 'comint)
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
This adds @code{comint} to the global @code{features} list, so that
|
||||
|
|
@ -726,13 +726,13 @@ ensure that a file of definitions is loaded before it is byte-compiled
|
|||
by including a @code{provide} followed by a @code{require} for the same
|
||||
feature, as in the following example.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(provide 'my-feature) ; @r{Ignored by byte compiler,}
|
||||
; @r{evaluated by @code{load}.}
|
||||
(require 'my-feature) ; @r{Evaluated by byte compiler.}
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
The compiler ignores the @code{provide}, then processes the
|
||||
|
|
@ -762,7 +762,7 @@ package, which might or might not be loaded, or might or might not be
|
|||
present in a given version. @xref{Network Feature Testing}, for
|
||||
an example.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
features
|
||||
@result{} (bar bish)
|
||||
|
||||
|
|
@ -770,7 +770,7 @@ features
|
|||
@result{} foo
|
||||
features
|
||||
@result{} (foo bar bish)
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
When a file is loaded to satisfy an autoload, and it stops due to an
|
||||
error in the evaluation of its contents, any function definitions or
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Emacs Lisp Reference Manual.
|
||||
@c Copyright (C) 1990-1995, 1998, 2001-2012 Free Software Foundation, Inc.
|
||||
@c Copyright (C) 1990-1995, 1998, 2001-2012 Free Software Foundation, Inc.
|
||||
@c See the file elisp.texi for copying conditions.
|
||||
@setfilename ../../info/macros
|
||||
@node Macros, Customization, Functions, Top
|
||||
|
|
@ -110,7 +110,7 @@ If @var{environment} is provided, it specifies an alist of macro
|
|||
definitions that shadow the currently defined macros. Byte compilation
|
||||
uses this feature.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(defmacro inc (var)
|
||||
(list 'setq var (list '1+ var)))
|
||||
|
|
@ -132,7 +132,7 @@ uses this feature.
|
|||
(macroexpand '(inc2 r s))
|
||||
@result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.}
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
|
||||
|
|
@ -146,10 +146,10 @@ Repeating the example used for @code{macroexpand} above with
|
|||
@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does}
|
||||
expand the embedded calls to @code{inc}:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(macroexpand-all '(inc2 r s))
|
||||
@result{} (progn (setq r (1+ r)) (setq s (1+ s)))
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@end defun
|
||||
|
||||
|
|
@ -333,7 +333,7 @@ following macro (used to facilitate iteration) illustrates the
|
|||
problem. This macro allows us to write a ``for'' loop construct.
|
||||
|
||||
@findex for
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(defmacro for (var from init to final do &rest body)
|
||||
"Execute a simple \"for\" loop.
|
||||
|
|
@ -364,7 +364,7 @@ For example, (for i from 1 to 10 do (print i))."
|
|||
@print{}3 9
|
||||
@result{} nil
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
The arguments @code{from}, @code{to}, and @code{do} in this macro are
|
||||
|
|
@ -374,7 +374,7 @@ in those positions in the macro call.
|
|||
|
||||
Here's an equivalent definition simplified through use of backquote:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(defmacro for (var from init to final do &rest body)
|
||||
"Execute a simple \"for\" loop.
|
||||
|
|
@ -384,7 +384,7 @@ For example, (for i from 1 to 10 do (print i))."
|
|||
,@@body
|
||||
(inc ,var))))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Both forms of this definition (with backquote and without) suffer from
|
||||
the defect that @var{final} is evaluated on every iteration. If
|
||||
|
|
@ -399,7 +399,7 @@ producing an expansion that evaluates the argument expressions exactly
|
|||
once unless repeated evaluation is part of the intended purpose of the
|
||||
macro. Here is a correct expansion for the @code{for} macro:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(let ((i 1)
|
||||
(max 3))
|
||||
|
|
@ -408,11 +408,11 @@ macro. Here is a correct expansion for the @code{for} macro:
|
|||
(princ (format "%d %d" i square))
|
||||
(inc i)))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Here is a macro definition that creates this expansion:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(defmacro for (var from init to final do &rest body)
|
||||
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
|
||||
|
|
@ -422,7 +422,7 @@ Here is a macro definition that creates this expansion:
|
|||
,@@body
|
||||
(inc ,var))))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
Unfortunately, this fix introduces another problem,
|
||||
described in the following section.
|
||||
|
|
@ -435,7 +435,7 @@ described in the following section.
|
|||
follows to make the expansion evaluate the macro arguments the proper
|
||||
number of times:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(defmacro for (var from init to final do &rest body)
|
||||
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
|
||||
|
|
@ -447,14 +447,14 @@ number of times:
|
|||
,@@body
|
||||
(inc ,var))))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
@end ifnottex
|
||||
|
||||
The new definition of @code{for} has a new problem: it introduces a
|
||||
local variable named @code{max} which the user does not expect. This
|
||||
causes trouble in examples such as the following:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(let ((max 0))
|
||||
(for x from 0 to 10 do
|
||||
|
|
@ -462,7 +462,7 @@ causes trouble in examples such as the following:
|
|||
(if (< max this)
|
||||
(setq max this)))))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
The references to @code{max} inside the body of the @code{for}, which
|
||||
|
|
@ -478,7 +478,7 @@ put it into the program later. It will never appear anywhere except
|
|||
where put by @code{for}. Here is a definition of @code{for} that works
|
||||
this way:
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
@group
|
||||
(defmacro for (var from init to final do &rest body)
|
||||
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
|
||||
|
|
@ -489,7 +489,7 @@ this way:
|
|||
,@@body
|
||||
(inc ,var)))))
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
This creates an uninterned symbol named @code{max} and puts it in the
|
||||
|
|
|
|||
|
|
@ -248,7 +248,7 @@ The length of the array is fixed once you create it; you cannot
|
|||
change the length of an existing array.
|
||||
|
||||
@item
|
||||
For purposes of evaluation, the array is a constant---in other words,
|
||||
For purposes of evaluation, the array is a constant---i.e.,
|
||||
it evaluates to itself.
|
||||
|
||||
@item
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Emacs Lisp Reference Manual.
|
||||
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
|
||||
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
|
||||
@c See the file elisp.texi for copying conditions.
|
||||
@setfilename ../../info/symbols
|
||||
@node Symbols, Evaluation, Hash Tables, Top
|
||||
|
|
@ -91,7 +91,7 @@ the contents of a symbol's function cell, use the function
|
|||
@code{symbol-function} (@pxref{Function Cells}).
|
||||
|
||||
The property list cell normally should hold a correctly formatted
|
||||
property list. To get a symbol's function cell, use the function
|
||||
property list. To get a symbol's property list, use the function
|
||||
@code{symbol-plist}. @xref{Property Lists}.
|
||||
|
||||
The function cell or the value cell may be @dfn{void}, which means
|
||||
|
|
@ -311,7 +311,7 @@ The argument @var{name} may also be a symbol; in that case,
|
|||
the function returns @var{name} if @var{name} is interned
|
||||
in the specified obarray, and otherwise @code{nil}.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(intern-soft "frazzle") ; @r{No such symbol exists.}
|
||||
@result{} nil
|
||||
(make-symbol "frazzle") ; @r{Create an uninterned one.}
|
||||
|
|
@ -332,7 +332,7 @@ in the specified obarray, and otherwise @code{nil}.
|
|||
(eq sym 'frazzle) ; @r{And it is the same one.}
|
||||
@result{} t
|
||||
@end group
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@defvar obarray
|
||||
|
|
@ -347,7 +347,7 @@ This function calls @var{function} once with each symbol in the obarray
|
|||
omitted, it defaults to the value of @code{obarray}, the standard
|
||||
obarray for ordinary symbols.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(setq count 0)
|
||||
@result{} 0
|
||||
(defun count-syms (s)
|
||||
|
|
@ -357,7 +357,7 @@ obarray for ordinary symbols.
|
|||
@result{} nil
|
||||
count
|
||||
@result{} 1871
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
See @code{documentation} in @ref{Accessing Documentation}, for another
|
||||
example using @code{mapatoms}.
|
||||
|
|
@ -463,12 +463,12 @@ This function sets @var{symbol}'s property list to @var{plist}.
|
|||
Normally, @var{plist} should be a well-formed property list, but this is
|
||||
not enforced. The return value is @var{plist}.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(setplist 'foo '(a 1 b (2 3) c nil))
|
||||
@result{} (a 1 b (2 3) c nil)
|
||||
(symbol-plist 'foo)
|
||||
@result{} (a 1 b (2 3) c nil)
|
||||
@end smallexample
|
||||
@end example
|
||||
|
||||
For symbols in special obarrays, which are not used for ordinary
|
||||
purposes, it may make sense to use the property list cell in a
|
||||
|
|
@ -493,7 +493,7 @@ This function puts @var{value} onto @var{symbol}'s property list under
|
|||
the property name @var{property}, replacing any previous property value.
|
||||
The @code{put} function returns @var{value}.
|
||||
|
||||
@smallexample
|
||||
@example
|
||||
(put 'fly 'verb 'transitive)
|
||||
@result{}'transitive
|
||||
(put 'fly 'noun '(a buzzing little bug))
|
||||
|
|
@ -502,14 +502,14 @@ The @code{put} function returns @var{value}.
|
|||
@result{} transitive
|
||||
(symbol-plist 'fly)
|
||||
@result{} (verb transitive noun (a buzzing little bug))
|
||||
@end smallexample
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@node Other Plists
|
||||
@subsection Property Lists Outside Symbols
|
||||
|
||||
These functions are useful for manipulating property lists
|
||||
that are stored in places other than symbols:
|
||||
not stored in symbols:
|
||||
|
||||
@defun plist-get plist property
|
||||
This returns the value of the @var{property} property stored in the
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue