Commit ddff3351 authored by Glenn Morris's avatar Glenn Morris
Browse files

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.
parent 9824f505
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):
......
@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
......
@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
......
@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