Commit 666b903b authored by Glenn Morris's avatar Glenn Morris
Browse files

Merge from emacs-24; up to 2012-04-21T14:12:27Z!sdl.web@gmail.com

parents 8f6b6da8 0a454caf
......@@ -31,6 +31,15 @@ its own at the start of a line. It looks better if you reword/respace
things to avoid these. (AFAIK, there is no way to find these except
paging through the whole manual.) This should be the very last thing
you do, since any change can alter the layout.
(Actually, there is probably little point in trying to do this.
It's only really relevant if printed versions of the manuals are going
to be published. End-users are not likely to print out all 1000+
pages of the manuals, and even if they do, the resulting page breaks
depend on what paper and font size they use. This also means that if
you _are_ going to do this, it should be done with the paper and font
size that the GNU Press are going to use when they print the manuals.
I think this is different to what you get if you just use eg `make
emacs.pdf' (e.g., enable "smallbook").
** Check the keybindings in the refcards are correct, and add any new ones.
Regenerate the pdf versions in etc/refcards/.
......
2012-05-09 Chong Yidong <cyd@gnu.org>
* frames.texi (Mouse References, Mouse Commands): Fix index
entries (Bug#11362).
2012-05-09 Glenn Morris <rgm@gnu.org>
* custom.texi (Customization Groups, Custom Themes, Examining):
Improve page breaks.
* rmail.texi (Rmail Display): Use example rather than smallexample.
* calendar.texi: Convert inforefs to refs.
* dired.texi (Dired Enter): Improve page break.
* abbrevs.texi (Abbrev Concepts): Copyedits.
* maintaining.texi (Registering, Tag Syntax):
Tweak line and page breaks.
* programs.texi (Programs, Electric C): Copyedits.
(Program Modes): Add xref to Fortran.
(Left Margin Paren): Remove what was (oddly enough) the only use
of defvar in the entire Emacs manual.
(Hungry Delete): Remove footnote about ancient Emacs version.
(Other C Commands): Use example rather than smallexample.
* text.texi (Pages, Filling, Foldout, Org Mode, HTML Mode)
(Nroff Mode, Enriched Indentation, Table Rows and Columns):
Tweak line and page breaks.
* modes.texi (Major Modes, Minor Modes): Reword to improve page-breaks.
(Major Modes): Use example rather than smallexample.
* mule.texi (Output Coding): Reword to improve page-breaks.
* frames.texi (Fonts): Tweak line and page breaks.
Use example rather than smallexample. Change cross-reference.
(Text-Only Mouse): Fix xref.
* buffers.texi (Buffers, Kill Buffer, Several Buffers)
(Indirect Buffers): Tweak line- and page-breaks.
* fixit.texi (Fixit, Undo): Reword to improve page-breaks.
2012-05-05 Glenn Morris <rgm@gnu.org>
* custom.texi (Customization Groups, Custom Themes, Examining):
......
......@@ -67,6 +67,7 @@ for doing so on MS-DOS).
@node Mouse Commands
@section Mouse Commands for Editing
@cindex mouse buttons (what they do)
@cindex mouse, selecting text using
@kindex Mouse-1
@kindex Mouse-2
......@@ -106,6 +107,7 @@ setting the variable @code{x-mouse-click-focus-ignore-position} to
selects the frame, without doing anything else; clicking again selects
the window and sets the cursor position.
@cindex mouse, dragging
@findex mouse-set-region
Holding down @kbd{Mouse-1} and ``dragging'' the mouse over a stretch
of text activates the region around that text
......@@ -235,8 +237,8 @@ Select the text you drag across, in the form of whole lines.
@node Mouse References
@section Following References with the Mouse
@kindex Mouse-1 @r{(selection)}
@kindex Mouse-2 @r{(selection)}
@kindex Mouse-1 @r{(on buttons)}
@kindex Mouse-2 @r{(on buttons)}
@cindex hyperlinks
@cindex links
@cindex text buttons
......
2012-05-09 Glenn Morris <rgm@gnu.org>
* emacs-lisp-intro.texi (Making Errors): Don't mention Emacs 20.
(Void Function, Wrong Type of Argument, Recursion with list)
(Simple Extension): Assume a non-ancient Emacs.
(Void Variable, Switching Buffers): Improve page breaks.
* emacs-lisp-intro.texi: Update GNU Press contact details.
2012-05-05 Glenn Morris <rgm@gnu.org>
* emacs-lisp-intro.texi (Making Errors): Don't mention Emacs 20.
......
......@@ -238,7 +238,7 @@ GNU Press, @hfill @uref{http://www.fsf.org/campaigns/gnu-press/}@*
a division of the @hfill email: @email{sales@@fsf.org}@*
Free Software Foundation, Inc. @hfill Tel: +1 (617) 542-5942@*
51 Franklin Street, Fifth Floor @hfill Fax: +1 (617) 542-2652@*
Boston, MA 02110-1301 USA
Boston, MA 02110-1301 USA
@end iftex
@ifnottex
......@@ -249,7 +249,7 @@ GNU Press, http://www.fsf.org/campaigns/gnu-press/
a division of the email: sales@@fsf.org
Free Software Foundation, Inc. Tel: +1 (617) 542-5942
51 Franklin Street, Fifth Floor Fax: +1 (617) 542-2652
Boston, MA 02110-1301 USA
Boston, MA 02110-1301 USA
@end example
@end ifnottex
......
2012-05-09 Glenn Morris <rgm@gnu.org>
* Makefile.in (clean, mostlyclean): Add some more vol1/2 items.
* two-volume.make (emacsdir): New.
(tex): Add directory with emacsver.texi to TEXINPUTS.
* minibuf.texi (Minibuffer History, Basic Completion):
Tweak page breaks.
* internals.texi (Garbage Collection, Memory Usage)
(Writing Emacs Primitives): Tweak page breaks.
* streams.texi (Output Variables): Improve page break.
* edebug.texi (Edebug Display Update): Improve page break.
* compile.texi (Disassembly): Condense the examples.
* 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.
* lists.texi (List-related Predicates, List Variables):
Tweak page-breaks.
(Sets And Lists): Convert inforef to xref.
* text.texi (Auto Filling): Don't mention Emacs 19.
* commands.texi (Event Input Misc): Don't mention unread-command-char.
* numbers.texi (Predicates on Numbers): Don't mention Emacs 18.
* objects.texi (Process Type, Overlay Type): Tweak page-breaks.
* intro.texi (Caveats): Copyedit.
(Lisp History): Convert inforef to xref.
(Lisp History, Printing Notation, Version Info): Improve page-breaks.
* elisp.texi (DATE): Forgot to change the month in 2012-04-21 change.
2012-05-08 Glenn Morris <rgm@gnu.org>
* two.el: Remove; unused since creation of two-volume.make.
......
......@@ -132,10 +132,11 @@ elisp.pdf: $(srcs)
mostlyclean:
rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \
*.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs
rm -f elisp[12]*
rm -f elisp[12]* vol[12].tmp
clean: mostlyclean
rm -f elisp.dvi elisp.pdf elisp.ps vol[12].pdf
rm -f elisp.dvi elisp.pdf elisp.ps
rm -f vol[12].dvi vol[12].pdf vol[12].ps
rm -rf elisp.html
rm -f emacs-lispref-${version}.tar*
......
......@@ -637,41 +637,34 @@ Lisp source; these do not appear in the output of @code{disassemble}.
@end group
@group
0 varref integer ; @r{Get the value of @code{integer}}
; @r{and push it onto the stack.}
1 constant 1 ; @r{Push 1 onto stack.}
0 varref integer ; @r{Get the value of @code{integer} and}
; @r{push it onto the stack.}
1 constant 1 ; @r{Push 1 onto stack.}
@end group
@group
2 eqlsign ; @r{Pop top two values off stack, compare}
; @r{them, and push result onto stack.}
2 eqlsign ; @r{Pop top two values off stack, compare}
; @r{them, and push result onto stack.}
@end group
@group
3 goto-if-nil 1 ; @r{Pop and test top of stack;}
; @r{if @code{nil}, go to 1,}
; @r{else continue.}
6 constant 1 ; @r{Push 1 onto top of stack.}
7 return ; @r{Return the top element}
; @r{of the stack.}
3 goto-if-nil 1 ; @r{Pop and test top of stack;}
; @r{if @code{nil}, go to 1, else continue.}
6 constant 1 ; @r{Push 1 onto top of stack.}
7 return ; @r{Return the top element of the stack.}
@end group
@group
8:1 varref integer ; @r{Push value of @code{integer} onto stack.}
9 constant factorial ; @r{Push @code{factorial} onto stack.}
10 varref integer ; @r{Push value of @code{integer} onto stack.}
11 sub1 ; @r{Pop @code{integer}, decrement value,}
; @r{push new value onto stack.}
12 call 1 ; @r{Call function @code{factorial} using}
; @r{the first (i.e., the top) element}
; @r{of the stack as the argument;}
; @r{push returned value onto stack.}
8:1 varref integer ; @r{Push value of @code{integer} onto stack.}
9 constant factorial ; @r{Push @code{factorial} onto stack.}
10 varref integer ; @r{Push value of @code{integer} onto stack.}
11 sub1 ; @r{Pop @code{integer}, decrement value,}
; @r{push new value onto stack.}
12 call 1 ; @r{Call function @code{factorial} using first}
; @r{(i.e. top) stack element as argument;}
; @r{push returned value onto stack.}
@end group
@group
13 mult ; @r{Pop top two values off stack, multiply}
; @r{them, and push result onto stack.}
14 return ; @r{Return the top element of stack.}
13 mult ; @r{Pop top two values off stack, multiply}
; @r{them, and push result onto stack.}
14 return ; @r{Return the top element of the stack.}
@end group
@end example
......@@ -693,70 +686,56 @@ The @code{silly-loop} function is somewhat more complex:
@print{} byte-code for silly-loop:
doc: Return time before and after N iterations of a loop.
args: (n)
@end group
0 constant current-time-string ; @r{Push}
; @r{@code{current-time-string}}
@group
0 constant current-time-string ; @r{Push @code{current-time-string}}
; @r{onto top of stack.}
@end group
@group
1 call 0 ; @r{Call @code{current-time-string}}
; @r{with no argument,}
; @r{pushing result onto stack.}
1 call 0 ; @r{Call @code{current-time-string} with no}
; @r{argument, push result onto stack.}
@end group
@group
2 varbind t1 ; @r{Pop stack and bind @code{t1}}
; @r{to popped value.}
2 varbind t1 ; @r{Pop stack and bind @code{t1} to popped value.}
@end group
@group
3:1 varref n ; @r{Get value of @code{n} from}
; @r{the environment and push}
; @r{the value onto the stack.}
4 sub1 ; @r{Subtract 1 from top of stack.}
3:1 varref n ; @r{Get value of @code{n} from the environment}
; @r{and push the value on the stack.}
4 sub1 ; @r{Subtract 1 from top of stack.}
@end group
@group
5 dup ; @r{Duplicate the top of the stack;}
; @r{i.e., copy the top of}
; @r{the stack and push the}
; @r{copy onto the stack.}
6 varset n ; @r{Pop the top of the stack,}
; @r{and bind @code{n} to the value.}
; @r{In effect, the sequence @code{dup varset}}
; @r{copies the top of the stack}
; @r{into the value of @code{n}}
; @r{without popping it.}
5 dup ; @r{Duplicate top of stack; i.e. copy the top}
; @r{of the stack and push copy onto stack.}
6 varset n ; @r{Pop the top of the stack,}
; @r{and bind @code{n} to the value.}
;; @r{(In effect, the sequence @code{dup varset} copies the top of the stack}
;; @r{into the value of @code{n} without popping it.)}
@end group
@group
7 constant 0 ; @r{Push 0 onto stack.}
8 gtr ; @r{Pop top two values off stack,}
; @r{test if @var{n} is greater than 0}
; @r{and push result onto stack.}
7 constant 0 ; @r{Push 0 onto stack.}
8 gtr ; @r{Pop top two values off stack,}
; @r{test if @var{n} is greater than 0}
; @r{and push result onto stack.}
@end group
@group
9 goto-if-not-nil 1 ; @r{Goto 1 if @code{n} > 0}
; @r{(this continues the while loop)}
; @r{else continue.}
9 goto-if-not-nil 1 ; @r{Goto 1 if @code{n} > 0}
; @r{(this continues the while loop)}
; @r{else continue.}
@end group
@group
12 varref t1 ; @r{Push value of @code{t1} onto stack.}
12 varref t1 ; @r{Push value of @code{t1} onto stack.}
13 constant current-time-string ; @r{Push @code{current-time-string}}
; @r{onto top of stack.}
14 call 0 ; @r{Call @code{current-time-string} again.}
; @r{onto the top of the stack.}
14 call 0 ; @r{Call @code{current-time-string} again.}
@end group
@group
15 unbind 1 ; @r{Unbind @code{t1} in local environment.}
16 list2 ; @r{Pop top two elements off stack,}
; @r{create a list of them,}
; @r{and push list onto stack.}
17 return ; @r{Return value of the top of stack.}
15 unbind 1 ; @r{Unbind @code{t1} in local environment.}
16 list2 ; @r{Pop top two elements off stack, create a}
; @r{list of them, and push it onto stack.}
17 return ; @r{Return value of the top of stack.}
@end group
@end example
......@@ -93,8 +93,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
......@@ -159,8 +159,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
......@@ -257,9 +257,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
......@@ -811,10 +809,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
......@@ -824,7 +822,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
......@@ -990,7 +988,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)
......@@ -1000,7 +998,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
......@@ -1033,9 +1031,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
......@@ -1054,7 +1052,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
......@@ -1075,22 +1073,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
......@@ -1108,7 +1108,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
......@@ -1119,12 +1119,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{}
......@@ -1279,7 +1279,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
......@@ -1287,7 +1287,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
......@@ -1312,7 +1312,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
......@@ -1323,7 +1323,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
......
......@@ -157,7 +157,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{})
......@@ -168,6 +168,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")
......@@ -394,7 +396,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.
......@@ -673,9 +675,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"},
......@@ -687,9 +689,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
......@@ -699,37 +701,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.
......@@ -737,14 +739,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)))