[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r110277: Update docs for a bunch of 2
|
From: |
Chong Yidong |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r110277: Update docs for a bunch of 24.3 changes. |
|
Date: |
Sun, 30 Sep 2012 17:18:38 +0800 |
|
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 110277
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2012-09-30 17:18:38 +0800
message:
Update docs for a bunch of 24.3 changes.
* doc/emacs/killing.texi (Rectangles): Document copy-rectangle-as-kill.
* doc/emacs/search.texi (Special Isearch): Document the lax space search
feature and M-s SPC.
(Regexp Search): Move main search-whitespace-regexp description to
Special Isearch.
(Replace): Document replace-lax-whitespace.
* doc/emacs/basic.texi (Position Info): Document C-u M-=.
(Moving Point): Document move-to-column.
* doc/emacs/display.texi (Useless Whitespace): Add delete-trailing-lines.
* doc/emacs/misc.texi (emacsclient Options): Document the effect of
initial-buffer-choice on client frames. Document server-auth-dir.
Do not document server-host, which is bad security practice.
* doc/emacs/building.texi (Lisp Libraries): Docstring lookups can trigger
autoloading. Document help-enable-auto-load.
* doc/emacs/mini.texi (Yes or No Prompts): New node.
* doc/emacs/ack.texi (Acknowledgments): Remove obsolete packages.
* doc/lispref/commands.texi (Click Events): Define "mouse position list".
Remove mention of unimplemented horizontal scroll bars.
(Drag Events, Motion Events): Refer to "mouse position list".
(Accessing Mouse): Document posnp.
* doc/lispref/errors.texi (Standard Errors): Tweak arith-error description.
Tweak markup. Remove domain-error and friends, which seem to be
unused after the floating-point code revamp.
* doc/lispref/functions.texi (Obsolete Functions): Obsolescence also affects
documentation commands. Various clarifications.
(Declare Form): New node.
* doc/lispref/loading.texi (Autoload):
* doc/lispref/help.texi (Documentation Basics): The special sequences can
trigger autoloading.
* doc/lispref/macros.texi (Defining Macros): Move description of `declare' to
Declare Form node.
* doc/lispref/numbers.texi (Integer Basics): Copyedits.
(Float Basics): Consider IEEE floating point always available.
(Random Numbers): Document actual limits.
(Arithmetic Operations): Clarify division by zero. Don't mention
the machine-independence of negative division since it does not
happen in practice.
* doc/lispref/os.texi (Idle Timers): Minor clarifications.
(User Identification): Add system-users and system-groups.
* doc/lispref/strings.texi (String Basics): Copyedits.
* lisp/minibuffer.el (minibuffer-local-filename-syntax): Doc fix.
* lisp/server.el (server-host): Document the security implications.
(server-auth-key): Doc fix.
* lisp/startup.el (initial-buffer-choice): Doc fix.
* src/fns.c (Frandom): Doc fix.
modified:
doc/emacs/ChangeLog
doc/emacs/ack.texi
doc/emacs/basic.texi
doc/emacs/building.texi
doc/emacs/display.texi
doc/emacs/emacs.texi
doc/emacs/entering.texi
doc/emacs/help.texi
doc/emacs/killing.texi
doc/emacs/mini.texi
doc/emacs/misc.texi
doc/emacs/search.texi
doc/lispref/ChangeLog
doc/lispref/commands.texi
doc/lispref/elisp.texi
doc/lispref/errors.texi
doc/lispref/frames.texi
doc/lispref/functions.texi
doc/lispref/help.texi
doc/lispref/loading.texi
doc/lispref/macros.texi
doc/lispref/numbers.texi
doc/lispref/os.texi
doc/lispref/strings.texi
etc/NEWS
lisp/ChangeLog
lisp/minibuffer.el
lisp/server.el
lisp/startup.el
src/ChangeLog
src/fns.c
=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog 2012-09-27 06:51:35 +0000
+++ b/doc/emacs/ChangeLog 2012-09-30 09:18:38 +0000
@@ -1,3 +1,29 @@
+2012-09-30 Chong Yidong <address@hidden>
+
+ * killing.texi (Rectangles): Document copy-rectangle-as-kill.
+
+ * search.texi (Special Isearch): Document the lax space search
+ feature and M-s SPC.
+ (Regexp Search): Move main search-whitespace-regexp description to
+ Special Isearch.
+ (Replace): Document replace-lax-whitespace.
+
+ * basic.texi (Position Info): Document C-u M-=.
+ (Moving Point): Document move-to-column.
+
+ * display.texi (Useless Whitespace): Add delete-trailing-lines.
+
+ * misc.texi (emacsclient Options): Document the effect of
+ initial-buffer-choice on client frames. Document server-auth-dir.
+ Do not document server-host, which is bad security practice.
+
+ * building.texi (Lisp Libraries): Docstring lookups can trigger
+ autoloading. Document help-enable-auto-load.
+
+ * mini.texi (Yes or No Prompts): New node.
+
+ * ack.texi (Acknowledgments): Remove obsolete packages.
+
2012-09-27 Glenn Morris <address@hidden>
* cal-xtra.texi (Advanced Calendar/Diary Usage):
=== modified file 'doc/emacs/ack.texi'
--- a/doc/emacs/ack.texi 2012-08-15 16:29:11 +0000
+++ b/doc/emacs/ack.texi 2012-09-30 09:18:38 +0000
@@ -644,10 +644,9 @@
@item
Daniel LaLiberte wrote @file{edebug.el}, a source-level debugger for
Emacs Lisp; @file{cl-specs.el}, specifications to help @code{edebug}
-debug code written using David Gillespie's Common Lisp support;
address@hidden, a customizable package for printing lisp
-objects; and @file{isearch.el}, Emacs's incremental search minor mode.
-He also co-wrote @file{hideif.el} (q.v.@:).
+debug code written using David Gillespie's Common Lisp support; and
address@hidden, Emacs's incremental search minor mode. He also
+co-wrote @file{hideif.el} (q.v.@:).
@item
Karl Landstrom and Daniel Colascione wrote @file{js.el}, a mode for
@@ -1301,15 +1300,14 @@
Colin Walters wrote Ibuffer, an enhanced buffer menu.
@item
-Barry Warsaw wrote @file{assoc.el}, a set of utility functions for
-working with association lists; @file{cc-mode.el}, a mode for editing
-C, address@hidden, and Java code, based on earlier work by Dave Detlefs,
-Stewart Clamen, and Richard Stallman; @file{elp.el}, a profiler for
-Emacs Lisp programs; @file{man.el}, a mode for reading Unix manual
-pages; @file{regi.el}, providing an AWK-like functionality for use in
-lisp programs; @file{reporter.el}, providing customizable bug
-reporting for lisp packages; and @file{supercite.el}, a minor mode for
-quoting sections of mail messages and news articles.
+Barry Warsaw wrote @file{cc-mode.el}, a mode for editing C, address@hidden,
+and Java code, based on earlier work by Dave Detlefs, Stewart Clamen,
+and Richard Stallman; @file{elp.el}, a profiler for Emacs Lisp
+programs; @file{man.el}, a mode for reading Unix manual pages;
address@hidden, providing an AWK-like functionality for use in lisp
+programs; @file{reporter.el}, providing customizable bug reporting for
+lisp packages; and @file{supercite.el}, a minor mode for quoting
+sections of mail messages and news articles.
@item
Christoph Wedler wrote @file{antlr-mode.el}, a major mode for ANTLR
@@ -1351,9 +1349,8 @@
entirely in Emacs Lisp. He also contributed to Org mode (q.v.@:).
@item
-Mike Williams wrote @file{mouse-sel.el}, providing enhanced mouse
-selection; and @file{thingatpt.el}, a library of functions for finding
-the ``thing'' (word, line, s-expression) containing point.
+Mike Williams wrote @file{thingatpt.el}, a library of functions for
+finding the ``thing'' (word, line, s-expression) at point.
@item
Roland Winkler wrote @file{proced.el}, a system process editor.
=== modified file 'doc/emacs/basic.texi'
--- a/doc/emacs/basic.texi 2012-07-17 07:43:01 +0000
+++ b/doc/emacs/basic.texi 2012-09-30 09:18:38 +0000
@@ -267,7 +267,8 @@
Scroll one screen backward, and move point onscreen if necessary
(@code{scroll-down-command}). @xref{Scrolling}.
address@hidden M-x goto-char
address@hidden M-g c
address@hidden M-g c
@findex goto-char
Read a number @var{n} and move point to buffer position @var{n}.
Position 1 is the beginning of the buffer.
@@ -285,6 +286,13 @@
@xref{Select Buffer}, for the behavior of @kbd{M-g M-g} when you give it
a plain prefix argument.
address@hidden M-g @key{TAB}
address@hidden M-g TAB
address@hidden move-to-column
+Read a number @var{n} and move to column @var{n} in the current line.
+Column 0 is the leftmost column. If called with a prefix argument,
+move to the column number specified by the argument's numeric value.
+
@item C-x C-n
@kindex C-x C-n
@findex set-goal-column
@@ -619,12 +627,16 @@
@kindex M-=
@findex count-words-region
+ @kbd{M-=} (@code{count-words-region}) displays a message reporting
+the number of lines, words, and characters in the region
+(@pxref{Mark}, for an explanation of the region). With a prefix
+argument, @kbd{C-u M-=}, the command displays a count for the entire
+buffer.
+
@findex count-words
- @kbd{M-=} (@code{count-words-region}) displays a message reporting
-the number of lines, words, and characters in the region. @kbd{M-x
-count-words} displays a similar message for the entire buffer, or for
-the region if the region is @dfn{active}. @xref{Mark}, for an
-explanation of the region.
+ The command @kbd{M-x count-words} does the same job, but with a
+different calling convention. It displays a count for the region if
+the region is active, and for the buffer otherwise.
@kindex C-x =
@findex what-cursor-position
=== modified file 'doc/emacs/building.texi'
--- a/doc/emacs/building.texi 2012-09-17 03:24:32 +0000
+++ b/doc/emacs/building.texi 2012-09-30 09:18:38 +0000
@@ -1393,13 +1393,21 @@
@end example
@cindex autoload
- Some commands are @dfn{autoloaded}: when you run them, Emacs
+ Some commands are @dfn{autoloaded}; when you run them, Emacs
automatically loads the associated library first. For instance, the
@kbd{M-x compile} command (@pxref{Compilation}) is autoloaded; if you
call it, Emacs automatically loads the @code{compile} library first.
In contrast, the command @kbd{M-x recompile} is not autoloaded, so it
is unavailable until you load the @code{compile} library.
address@hidden help-enable-auto-load
+ Automatic loading can also occur when you look up the documentation
+of an autoloaded command (@pxref{Name Help}), if the documentation
+refers to other functions and variables in its library (loading the
+library lets Emacs properly set up the hyperlinks in the @file{*Help*}
+buffer). To disable this feature, change the variable
address@hidden to @code{nil}.
+
@vindex load-dangerous-libraries
@cindex Lisp files byte-compiled by XEmacs
By default, Emacs refuses to load compiled Lisp files which were
=== modified file 'doc/emacs/display.texi'
--- a/doc/emacs/display.texi 2012-08-05 09:24:55 +0000
+++ b/doc/emacs/display.texi 2012-09-30 09:18:38 +0000
@@ -1044,9 +1044,9 @@
@cindex whitespace, trailing
@vindex show-trailing-whitespace
It is easy to leave unnecessary spaces at the end of a line, or
-empty lines at the end of a file, without realizing it. In most
-cases, this @dfn{trailing whitespace} has no effect, but there are
-special circumstances where it matters, and it can be a nuisance.
+empty lines at the end of a buffer, without realizing it. In most
+cases, this @dfn{trailing whitespace} has no effect, but sometimes it
+can be a nuisance.
You can make trailing whitespace at the end of a line visible by
setting the buffer-local variable @code{show-trailing-whitespace} to
@@ -1061,9 +1061,13 @@
present.
@findex delete-trailing-whitespace
address@hidden delete-trailing-lines
Type @kbd{M-x delete-trailing-whitespace} to delete all trailing
-whitespace within the buffer. If the region is active, it deletes all
-trailing whitespace in the region instead.
+whitespace. This command deletes all extra spaces at the end of each
+line in the buffer, and all empty lines at the end of the buffer; to
+ignore the latter, change the varaible @code{delete-trailing-lines} to
address@hidden If the region is active, the command instead deletes
+extra spaces at the end of each line in the region.
@vindex indicate-empty-lines
@cindex unused lines
=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi 2012-09-27 06:51:35 +0000
+++ b/doc/emacs/emacs.texi 2012-09-30 09:18:38 +0000
@@ -267,6 +267,7 @@
* Minibuffer History:: Reusing recent minibuffer arguments.
* Repetition:: Re-executing commands that used the minibuffer.
* Passwords:: Entering passwords in the echo area.
+* Yes or No Prompts:: Replying yes or no in the echo area.
Completion
=== modified file 'doc/emacs/entering.texi'
--- a/doc/emacs/entering.texi 2012-05-27 01:25:06 +0000
+++ b/doc/emacs/entering.texi 2012-09-30 09:18:38 +0000
@@ -79,11 +79,6 @@
files on the command line, Emacs opens but does not display them.)
The value of @code{initial-buffer-choice} should be the name of
the desired file or directory.
address@hidden
address@hidden I do not think this should be mentioned. AFAICS it is just a
dodge
address@hidden around inhibit-startup-screen not being settable on a site-wide
basis.
-or @code{t}, which means to display the @file{*scratch*} buffer.
address@hidden ignore
@node Exiting
@section Exiting Emacs
=== modified file 'doc/emacs/help.texi'
--- a/doc/emacs/help.texi 2012-05-27 01:25:06 +0000
+++ b/doc/emacs/help.texi 2012-09-30 09:18:38 +0000
@@ -243,7 +243,7 @@
(That name appears as the default while you enter the argument.) For
example, if point is located following the text @samp{(make-vector
(car x)}, the innermost list containing point is the one that starts
-with @samp{(make-vector}, so @kbd{C-h f @key{RET}} will describe the
+with @samp{(make-vector}, so @kbd{C-h f @key{RET}} describes the
function @code{make-vector}.
@kbd{C-h f} is also useful just to verify that you spelled a
=== modified file 'doc/emacs/killing.texi'
--- a/doc/emacs/killing.texi 2012-09-19 06:51:33 +0000
+++ b/doc/emacs/killing.texi 2012-09-30 09:18:38 +0000
@@ -709,6 +709,9 @@
@item C-x r k
Kill the text of the region-rectangle, saving its contents as the
``last killed rectangle'' (@code{kill-rectangle}).
address@hidden C-x r M-w
+Save the text of the region-rectangle as the ``last killed rectangle''
+(@code{copy-rectangle-as-kill}).
@item C-x r d
Delete the text of the region-rectangle (@code{delete-rectangle}).
@item C-x r y
@@ -757,6 +760,12 @@
different yank commands have to be used. Yank-popping is not defined
for rectangles.
address@hidden C-x r M-w
address@hidden copy-rectangle-as-kill
+ @kbd{C-x r M-w} (@code{copy-rectangle-as-kill}) is the equivalent of
address@hidden for rectangles: it records the rectangle as the ``last
+killed rectangle'', without deleting the text from the buffer.
+
@kindex C-x r y
@findex yank-rectangle
To yank the last killed rectangle, type @kbd{C-x r y}
=== modified file 'doc/emacs/mini.texi'
--- a/doc/emacs/mini.texi 2012-05-27 01:25:06 +0000
+++ b/doc/emacs/mini.texi 2012-09-30 09:18:38 +0000
@@ -45,6 +45,7 @@
* Minibuffer History:: Reusing recent minibuffer arguments.
* Repetition:: Re-executing commands that used the minibuffer.
* Passwords:: Entering passwords in the echo area.
+* Yes or No Prompts:: Replying yes or no in the echo area.
@end menu
@node Minibuffer File
@@ -733,3 +734,53 @@
@key{ESC} to submit the password. Any other self-inserting character
key inserts the associated character into the password, and all other
input is ignored.
+
address@hidden Yes or No Prompts
address@hidden Yes or No Prompts
+
+ An Emacs command may require you to answer a ``yes or no'' question
+during the course of its execution. Such queries come in two main
+varieties.
+
address@hidden y or n prompt
+ For the first type of ``yes or no'' query, the prompt ends with
address@hidden(y or n)}. Such a query does not actually use the minibuffer;
+the prompt appears in the echo area, and you answer by typing either
address@hidden or @samp{n}, which immediately delivers the response. For
+example, if you type @kbd{C-x C-w} (@kbd{write-file}) to save a
+buffer, and enter the name of an existing file, Emacs issues a prompt
+like this:
+
address@hidden
+File `foo.el' exists; overwrite? (y or n)
address@hidden smallexample
+
address@hidden
+Because this query does not actually use the minibuffer, the usual
+minibuffer editing commands cannot be used. However, you can perform
+some window scrolling operations while the query is active: @kbd{C-l}
+recenters the selected window; @kbd{M-v} (or @key{PageDown} or
address@hidden) scrolls forward; @kbd{C-v} (or @key{PageUp}, or
address@hidden) scrolls backward; @kbd{C-M-v} scrolls forward in the next
+window; and @kbd{C-M-S-v} scrolls backward in the next window. Typing
address@hidden dismisses the query, and quits the command that issued it
+(@pxref{Quitting}).
+
address@hidden yes or no prompt
+ The second type of ``yes or no'' query is typically employed if
+giving the wrong answer would have serious consequences; it uses the
+minibuffer, and features a prompt ending with @samp{(yes or no)}. For
+example, if you invoke @kbd{C-x k} (@code{kill-buffer}) on a
+file-visiting buffer with unsaved changes, Emacs activates the
+minibuffer with a prompt like this:
+
address@hidden
+Buffer foo.el modified; kill anyway? (yes or no)
address@hidden smallexample
+
address@hidden
+To answer, you must type @samp{yes} or @samp{no} into the minibuffer,
+followed by @key{RET}. The minibuffer behaves as described in the
+previous sections; you can switch to another window with @kbd{C-x o},
+use the history commands @kbd{M-p} and @kbd{M-f}, etc. Type @kbd{C-g}
+to quit the minibuffer and the querying command.
=== modified file 'doc/emacs/misc.texi'
--- a/doc/emacs/misc.texi 2012-09-19 17:35:18 +0000
+++ b/doc/emacs/misc.texi 2012-09-30 09:18:38 +0000
@@ -1509,15 +1509,11 @@
@cindex client frame
@item -c
Create a new graphical @dfn{client frame}, instead of using an
-existing Emacs frame. If you omit a filename argument while supplying
-the @samp{-c} option, the new frame displays the @file{*scratch*}
-buffer (@pxref{Buffers}). See below for the special behavior of
address@hidden C-c} in a client frame.
-
-If Emacs is unable to create a new graphical frame (e.g.@: if it is
-unable to connect to the X server), it tries to create a text terminal
-client frame, as though you had supplied the @samp{-t} option instead
-(see below).
+existing Emacs frame. See below for the special behavior of @kbd{C-x
+C-c} in a client frame. If Emacs cannot create a new graphical frame
+(e.g.@: if it cannot connect to the X server), it tries to create a
+text terminal client frame, as though you had supplied the @samp{-t}
+option instead.
On MS-Windows, a single Emacs session cannot display frames on both
graphical and text terminals, nor on multiple text terminals. Thus,
@@ -1525,6 +1521,11 @@
option, like the @samp{-t} option, creates a new frame in the server's
current text terminal. @xref{Windows Startup}.
+If you omit a filename argument while supplying the @samp{-c} option,
+the new frame displays the @file{*scratch*} buffer by default. If
address@hidden is a string (@pxref{Entering Emacs}), the
+new frame displays that file or directory instead.
+
@item -F @var{alist}
@itemx address@hidden
Set the parameters for a newly-created graphical frame
@@ -1545,38 +1546,24 @@
@item -f @var{server-file}
@itemx address@hidden
@cindex @env{EMACS_SERVER_FILE} environment variable
address@hidden server file
address@hidden server-use-tcp
address@hidden server-host
Specify a @dfn{server file} for connecting to an Emacs server via TCP.
An Emacs server usually uses an operating system feature called a
``local socket'' to listen for connections. Some operating systems,
such as Microsoft Windows, do not support local sockets; in that case,
-Emacs uses TCP instead. When you start the Emacs server, Emacs
-creates a server file containing some TCP information that
address@hidden needs for making the connection. By default,
-the server file is in @file{~/.emacs.d/server/}. On Microsoft
-Windows, if @command{emacsclient} does not find the server file there,
-it looks in the @file{.emacs.d/server/} subdirectory of the directory
-pointed to by the @env{APPDATA} environment variable. You can tell
address@hidden to use a specific server file with the @samp{-f}
-or @samp{--server-file} option, or by setting the
address@hidden environment variable.
-
-Even if local sockets are available, you can tell Emacs to use TCP by
-setting the variable @code{server-use-tcp} to @code{t}. One advantage
-of TCP is that the server can accept connections from remote machines.
-For this to work, you must (i) set the variable @code{server-host} to
-the hostname or IP address of the machine on which the Emacs server
-runs, and (ii) provide @command{emacsclient} with the server file.
-(One convenient way to do the latter is to put the server file on a
-networked file system such as NFS.)
-
+the server communicates with @command{emacsclient} via TCP.
+
address@hidden server-auth-dir
address@hidden server file
@vindex server-port
- When the Emacs server is using TCP, the variable @code{server-port}
-determines the port number to listen on; the default value,
address@hidden, means to choose a random port when the server starts.
+When you start a TCP Emacs server, Emacs creates a @dfn{server file}
+containing the TCP information to be used by @command{emacsclient} to
+connect to the server. The variable @code{server-auth-dir} specifies
+the directory containing the server file; by default, this is
address@hidden/.emacs.d/server/}. To tell @command{emacsclient} to connect
+to the server over TCP with a specific server file, use the @samp{-f}
+or @samp{--server-file} option, or set the @env{EMACS_SERVER_FILE}
+environment variable.
@item -n
@itemx --no-wait
@@ -1606,19 +1593,14 @@
@itemx --tty
@itemx -nw
Create a new client frame on the current text terminal, instead of
-using an existing Emacs frame. This is similar to the @samp{-c}
-option, above, except that it creates a text terminal frame
-(@pxref{Non-Window Terminals}). If you omit a filename argument while
-supplying this option, the new frame displays the @file{*scratch*}
-buffer (@pxref{Buffers}). See below for the special behavior of
address@hidden C-c} in a client frame.
+using an existing Emacs frame. This behaves just like the @samp{-c}
+option, described above, except that it creates a text terminal frame
+(@pxref{Non-Window Terminals}).
-On MS-Windows, a single Emacs session cannot display frames on both
-graphical and text terminals, nor on multiple text terminals. Thus,
-if the Emacs server is using the graphical display, @samp{-t} behaves
-like @samp{-c} (see above); whereas if the Emacs server is running on
-a text terminal, it creates a new frame in its current text terminal.
address@hidden Startup}.
+On MS-Windows, @samp{-t} behaves just like @samp{-c} if the Emacs
+server is using the graphical display, but if the Emacs server is
+running on a text terminal, it creates a new frame in the current text
+terminal.
@end table
The new graphical or text terminal frames created by the @samp{-c}
=== modified file 'doc/emacs/search.texi'
--- a/doc/emacs/search.texi 2012-05-27 01:25:06 +0000
+++ b/doc/emacs/search.texi 2012-09-30 09:18:38 +0000
@@ -17,7 +17,6 @@
(@pxref{Operating on Files}), or ask the @code{grep} program to do it
(@pxref{Grep Searching}).
-
@menu
* Incremental Search:: Search happens as you type the string.
* Nonincremental Search:: Specify entire string and then search.
@@ -218,6 +217,24 @@
Some of the characters you type during incremental search have
special effects.
address@hidden lax space matching
address@hidden M-s SPC @r{(Incremental search)}
address@hidden SPC @r{(Incremental search)}
address@hidden isearch-toggle-lax-whitespace
address@hidden search-whitespace-regexp
+ By default, incremental search performs @dfn{lax space matching}:
+each space, or sequence of spaces, matches any sequence of one or more
+spaces in the text. Hence, @samp{foo bar} matches @samp{foo bar},
address@hidden bar}, @samp{foo bar}, and so on (but not @samp{foobar}).
+More precisely, Emacs matches each sequence of space characters in the
+search string to a regular expression specified by the variable
address@hidden For example, set it to
address@hidden"[[:space:]\n]+"} to make spaces match sequences of newlines as
+well as spaces. To toggle lax space matching, type @kbd{M-s SPC}
+(@code{isearch-toggle-lax-whitespace}). To disable this feature
+entirely, change @code{search-whitespace-regexp} to @code{nil}; then
+each space in the search string matches exactly one space
+
If the search string you entered contains only lower-case letters,
the search is case-insensitive; as long as an upper-case letter exists
in the search string, the search becomes case-sensitive. If you
@@ -492,12 +509,12 @@
They also have separate search rings, which you can access with
@kbd{M-p} and @kbd{M-n}.
address@hidden search-whitespace-regexp
- If you type @key{SPC} in incremental regexp search, it matches any
-sequence of whitespace characters, including newlines. If you want to
-match just a space, type @kbd{C-q @key{SPC}}. You can control what a
-bare space matches by setting the variable
address@hidden to the desired regexp.
+ Just as in ordinary incremental search, any @key{SPC} typed in
+incremental regexp search matches any sequence of one or more
+whitespace characters. The variable @code{search-whitespace-regexp}
+specifies the regexp for the lax space matching, and @kbd{M-s SPC}
+(@code{isearch-toggle-lax-whitespace}) toggles the feature.
address@hidden Isearch}.
In some cases, adding characters to the regexp in an incremental
regexp search can make the cursor move back and start again. For
@@ -974,6 +991,13 @@
is possible to perform several replacements in parallel, using the
command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
address@hidden replace-lax-whitespace
+ Unlike incremental search, the replacement commands do not use lax
+space matching (@pxref{Special Isearch}) by default. To enable lax
+space matching for replacement, change the variable
address@hidden to @code{t}. (This only affects how
+Emacs finds the text to replace, not the replacement text.)
+
@menu
* Unconditional Replace:: Replacing all matches for a string.
* Regexp Replace:: Replacing all matches for a regexp.
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-09-28 16:02:31 +0000
+++ b/doc/lispref/ChangeLog 2012-09-30 09:18:38 +0000
@@ -1,3 +1,45 @@
+2012-09-30 Chong Yidong <address@hidden>
+
+ * commands.texi (Click Events): Define "mouse position list".
+ Remove mention of unimplemented horizontal scroll bars.
+ (Drag Events, Motion Events): Refer to "mouse position list".
+ (Accessing Mouse): Document posnp.
+
+ * errors.texi (Standard Errors): Tweak arith-error description.
+ Tweak markup. Remove domain-error and friends, which seem to be
+ unused after the floating-point code revamp.
+
+ * functions.texi (Obsolete Functions): Obsolescence also affects
+ documentation commands. Various clarifications.
+ (Declare Form): New node.
+
+ * strings.texi (String Basics): Copyedits.
+
+ * os.texi (Idle Timers): Minor clarifications.
+ (User Identification): Add system-users and system-groups.
+
+ * macros.texi (Defining Macros): Move description of `declare' to
+ Declare Form node.
+
+ * loading.texi (Autoload):
+ * help.texi (Documentation Basics): The special sequences can
+ trigger autoloading.
+
+ * numbers.texi (Integer Basics): Copyedits.
+ (Float Basics): Consider IEEE floating point always available.
+ (Random Numbers): Document actual limits.
+ (Arithmetic Operations): Clarify division by zero. Don't mention
+ the machine-independence of negative division since it does not
+ happen in practice.
+
+2012-09-28 Chong Yidong <address@hidden>
+
+ * os.texi (Startup Summary): Document leim-list.el change.
+
+2012-09-25 Chong Yidong <address@hidden>
+
+ * functions.texi (Defining Functions): defun is now a macro.
+
2012-09-28 Leo Liu <address@hidden>
* files.texi (Files): Fix typo.
=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2012-09-12 19:16:36 +0000
+++ b/doc/lispref/commands.texi 2012-09-30 09:18:38 +0000
@@ -1275,12 +1275,21 @@
@var{event-type} is @code{mouse-1}.
@item @var{position}
-This is the position where the mouse click occurred. The actual
-format of @var{position} depends on what part of a window was clicked
-on.
-
-For mouse click events in the text area, mode line, header line, or in
-the marginal areas, @var{position} has this form:
address@hidden mouse position list
+This is a @dfn{mouse position list} specifying where the mouse click
+occurred; see below for details.
+
address@hidden @var{click-count}
+This is the number of rapid repeated presses so far of the same mouse
+button. @xref{Repeat Events}.
address@hidden table
+
+ To access the contents of a mouse position list in the
address@hidden slot of a click event, you should typically use the
+functions documented in @ref{Accessing Mouse}. The explicit format of
+the list depends on where the click occurred. For clicks in the text
+area, mode line, header line, or in the fringe or marginal areas, the
+mouse position list has the form
@example
(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
@@ -1289,18 +1298,16 @@
@end example
@noindent
-The meanings of these list elements are documented below.
address@hidden Mouse}, for functions that let you easily access these
-elements.
+The meanings of these list elements are as follows:
@table @asis
@item @var{window}
-This is the window in which the click occurred.
+The window in which the click occurred.
@item @var{pos-or-area}
-This is the buffer position of the character clicked on in the text
-area, or if clicked outside the text area, it is the window area in
-which the click occurred. It is one of the symbols @code{mode-line},
+The buffer position of the character clicked on in the text area; or,
+if the click was outside the text area, the window area where it
+occurred. It is one of the symbols @code{mode-line},
@code{header-line}, @code{vertical-line}, @code{left-margin},
@code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
@@ -1310,22 +1317,23 @@
by Emacs. @xref{Key Sequence Input}.
@item @var{x}, @var{y}
-These are the relative pixel coordinates of the click. For clicks in
-the text area of a window, the coordinate origin @code{(0 . 0)} is
-taken to be the top left corner of the text area. @xref{Window
-Sizes}. For clicks in a mode line or header line, the coordinate
-origin is the top left corner of the window itself. For fringes,
-margins, and the vertical border, @var{x} does not have meaningful
-data. For fringes and margins, @var{y} is relative to the bottom edge
-of the header line. In all cases, the @var{x} and @var{y} coordinates
-increase rightward and downward respectively.
+The relative pixel coordinates of the click. For clicks in the text
+area of a window, the coordinate origin @code{(0 . 0)} is taken to be
+the top left corner of the text area. @xref{Window Sizes}. For
+clicks in a mode line or header line, the coordinate origin is the top
+left corner of the window itself. For fringes, margins, and the
+vertical border, @var{x} does not have meaningful data. For fringes
+and margins, @var{y} is relative to the bottom edge of the header
+line. In all cases, the @var{x} and @var{y} coordinates increase
+rightward and downward respectively.
@item @var{timestamp}
-This is the time at which the event occurred, in milliseconds.
+The time at which the event occurred, as an integer number of
+milliseconds since a system-dependent initial time.
@item @var{object}
-This is either @code{nil} if there is no string-type text property at
-the click position, or a cons cell of the form (@var{string}
+Either @code{nil} if there is no string-type text property at the
+click position, or a cons cell of the form (@var{string}
. @var{string-pos}) if there is one:
@table @asis
@@ -1371,8 +1379,7 @@
@code{nil}, those of the character glyph clicked on.
@end table
address@hidden 1
-For mouse clicks on a scroll-bar, @var{position} has this form:
+For clicks on a scroll bar, @var{position} has this form:
@example
(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp}
@var{part})
@@ -1380,32 +1387,35 @@
@table @asis
@item @var{window}
-This is the window whose scroll-bar was clicked on.
+The window whose scroll bar was clicked on.
@item @var{area}
-This is the scroll bar where the click occurred. It is one of the
-symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
+This is the symbol @code{vertical-scroll-bar}.
@item @var{portion}
-This is the distance of the click from the top or left end of
-the scroll bar.
+The number of pixels from the top of the scroll bar to the click
+position. On some toolkits, including GTK+, Emacs cannot extract this
+data, so the value is always @code{0}.
@item @var{whole}
-This is the length of the entire scroll bar.
+The total length, in pixels, of the scroll bar. On some toolkits,
+including GTK+, Emacs cannot extract this data, so the value is always
address@hidden
@item @var{timestamp}
-This is the time at which the event occurred, in milliseconds.
+The time at which the event occurred, in milliseconds. On some
+toolkits, including GTK+, Emacs cannot extract this data, so the value
+is always @code{0}.
@item @var{part}
-This is the part of the scroll-bar which was clicked on. It is one
-of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
address@hidden, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
+The part of the scroll bar on which the click occurred. It is one of
+the symbols @code{handle} (the scroll bar handle), @code{above-handle}
+(the area above the handle), @code{below-handle} (the area below the
+handle), @code{up} (the up arrow at one end of the scroll bar), or
address@hidden (the down arrow at one end of the scroll bar).
address@hidden The `top', `bottom', and `end-scroll' codes don't seem to be
used.
@end table
address@hidden @var{click-count}
-This is the number of rapid repeated presses so far of the same mouse
-button. @xref{Repeat Events}.
address@hidden table
@node Drag Events
@subsection Drag Events
@@ -1429,10 +1439,9 @@
prefix @samp{drag-}. For example, dragging the mouse with button 2
held down generates a @code{drag-mouse-2} event. The second and third
elements of the event give the starting and ending position of the
-drag. They have the same form as @var{position} in a click event
-(@pxref{Click Events}) that is not on the scroll bar part of the
-window. You can access the second element of any mouse event in the
-same way, with no need to distinguish drag events from others.
+drag, as mouse position lists (@pxref{Click Events}). You can access
+the second element of any mouse event in the same way, with no need to
+distinguish drag events from others.
The @samp{drag-} prefix follows the modifier key prefixes such as
@samp{C-} and @samp{M-}.
@@ -1575,13 +1584,14 @@
(mouse-movement POSITION)
@end example
-The second element of the list describes the current position of the
-mouse, just as in a click event (@pxref{Click Events}).
address@hidden
address@hidden is a mouse position list (@pxref{Click Events}),
+specifying the current position of the mouse cursor.
-The special form @code{track-mouse} enables generation of motion events
-within its body. Outside of @code{track-mouse} forms, Emacs does not
-generate events for mere motion of the mouse, and these events do not
-appear. @xref{Mouse Tracking}.
+The special form @code{track-mouse} enables generation of motion
+events within its body. Outside of @code{track-mouse} forms, Emacs
+does not generate events for mere motion of the mouse, and these
+events do not appear. @xref{Mouse Tracking}.
@node Focus Events
@subsection Focus Events
@@ -1648,13 +1658,11 @@
@cindex @code{wheel-up} event
@cindex @code{wheel-down} event
@item (wheel-up @var{position})
address@hidden (wheel-down @var{position})
-These kinds of event are generated by moving a mouse wheel. Their
-usual meaning is a kind of scroll or zoom.
-
-The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event (@pxref{Click
-Events}).
address@hidden (wheel-down @var{position})
+These kinds of event are generated by moving a mouse wheel. The
address@hidden element is a mouse position list (@pxref{Click
+Events}), specifying the position of the mouse cursor when the event
+occurred.
@vindex mouse-wheel-up-event
@vindex mouse-wheel-down-event
@@ -1922,14 +1930,8 @@
This section describes convenient functions for accessing the data in
a mouse button or motion event.
- These two functions return the starting or ending position of a
-mouse-button event, as a list of this form (@pxref{Click Events}):
-
address@hidden
-(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
- @var{object} @var{text-pos} (@var{col} . @var{row})
- @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
address@hidden example
+ The following two functions return a mouse position list
+(@pxref{Click Events}), specifying the position of a mouse event.
@defun event-start event
This returns the starting position of @var{event}.
@@ -1948,9 +1950,15 @@
position such events have.
@end defun
address@hidden posnp object
+This function returns address@hidden if @var{object} is a mouse
+oposition list, in either of the formats documented in @ref{Click
+Events}); and @code{nil} otherwise.
address@hidden defun
+
@cindex mouse position list, accessing
- These functions take a position list as described above, and
-return various parts of it.
+ These functions take a mouse position list as argument, and return
+various parts of it:
@defun posn-window position
Return the window that @var{position} is in.
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2012-09-18 05:14:42 +0000
+++ b/doc/lispref/elisp.texi 2012-09-30 09:18:38 +0000
@@ -516,6 +516,7 @@
* Obsolete Functions:: Declaring functions obsolete.
* Inline Functions:: Defining functions that the compiler
will expand inline.
+* Declare Form:: Adding additional information about a function.
* Declaring Functions:: Telling the compiler that a function is defined.
* Function Safety:: Determining whether a function is safe to call.
* Related Topics:: Cross-references to specific Lisp primitives
=== modified file 'doc/lispref/errors.texi'
--- a/doc/lispref/errors.texi 2012-05-27 01:34:14 +0000
+++ b/doc/lispref/errors.texi 2012-09-30 09:18:38 +0000
@@ -37,78 +37,69 @@
@table @code
@item error
address@hidden"error"address@hidden
address@hidden
+The message is @samp{error}. @xref{Errors}.
@item quit
address@hidden"Quit"address@hidden
address@hidden
+The message is @samp{Quit}. @xref{Quitting}.
@item args-out-of-range
address@hidden"Args out of range"address@hidden
-This happens when trying to access an element beyond the range of a
-sequence or address@hidden
address@hidden Arrays Vectors}, @xref{Text}.
+The message is @samp{Args out of range}. This happens when trying to
+access an element beyond the range of a sequence, buffer, or other
+container-like object. @xref{Sequences Arrays Vectors}, and
address@hidden
@item arith-error
address@hidden"Arithmetic error"address@hidden
+The message is @samp{Arithmetic error}. This occurs when trying to
+perform integer division by zero. @xref{Numeric Conversions}, and
@xref{Arithmetic Operations}.
@item beginning-of-buffer
address@hidden"Beginning of buffer"address@hidden
address@hidden Motion}.
+The message is @samp{Beginning of buffer}. @xref{Character Motion}.
@item buffer-read-only
address@hidden"Buffer is read-only"address@hidden
address@hidden Only Buffers}.
+The message is @samp{Buffer is read-only}. @xref{Read Only Buffers}.
@item circular-list
address@hidden"List contains a loop"address@hidden
-This happens when some operations (e.g. resolving face names)
-encounter circular address@hidden
address@hidden Objects}.
+The message is @samp{List contains a loop}. This happens when a
+circular structure is encountered. @xref{Circular Objects}.
@item cl-assertion-failed
address@hidden"Assertion failed"address@hidden
-This happens when the @code{assert} macro fails a address@hidden
address@hidden,,, cl, Common Lisp Extensions}.
+The message is @samp{Assertion failed}. This happens when the
address@hidden macro fails a test. @xref{Assertions,,, cl, Common Lisp
+Extensions}.
@item coding-system-error
address@hidden"Invalid coding system"address@hidden
address@hidden and Coding Systems}.
+The message is @samp{Invalid coding system}. @xref{Lisp and Coding
+Systems}.
@item cyclic-function-indirection
address@hidden"Symbol's chain of function indirections contains a
loop"address@hidden
address@hidden Indirection}.
+The message is @samp{Symbol's chain of function indirections contains
+a loop}. @xref{Function Indirection}.
@item cyclic-variable-indirection
address@hidden"Symbol's chain of variable indirections contains a
loop"address@hidden
address@hidden Aliases}.
+The message is @samp{Symbol's chain of variable indirections contains
+a loop}. @xref{Variable Aliases}.
@item dbus-error
address@hidden"D-Bus error"address@hidden
-This is only defined if Emacs was compiled with D-Bus address@hidden
address@hidden and Events,,, dbus, D-Bus integration in Emacs}.
+The message is @samp{D-Bus error}. This is only defined if Emacs was
+compiled with D-Bus support. @xref{Errors and Events,,, dbus, D-Bus
+integration in Emacs}.
@item end-of-buffer
address@hidden"End of buffer"address@hidden
address@hidden Motion}.
+The message is @samp{End of buffer}. @xref{Character Motion}.
@item end-of-file
address@hidden"End of file during parsing"address@hidden
-Note that this is not a subcategory of @code{file-error},
-because it pertains to the Lisp reader, not to file I/address@hidden
address@hidden Functions}.
+The message is @samp{End of file during parsing}. Note that this is
+not a subcategory of @code{file-error}, because it pertains to the
+Lisp reader, not to file I/O. @xref{Input Functions}.
@item file-already-exists
-This is a subcategory of @address@hidden
address@hidden to Files}.
+This is a subcategory of @code{file-error}. @xref{Writing to Files}.
@item file-date-error
This is a subcategory of @code{file-error}. It occurs when
@code{copy-file} tries and fails to set the last-modification time of
-the output address@hidden
address@hidden Files}.
+the output file. @xref{Changing Files}.
@item file-error
We do not list the error-strings of this error and its subcategories,
@@ -116,122 +107,109 @@
alone when the error condition @code{file-error} is present. Thus,
the error-strings are not very relevant. However, these error symbols
do have @code{error-message} properties, and if no data is provided,
-the @code{error-message} property @emph{is} address@hidden
address@hidden
+the @code{error-message} property @emph{is} used. @xref{Files}.
@c jka-compr.el
@item compression-error
This is a subcategory of @code{file-error}, which results from
-problems handling a compressed address@hidden
address@hidden Programs Do Loading}.
+problems handling a compressed file. @xref{How Programs Do Loading}.
@c userlock.el
@item file-locked
-This is a subcategory of @address@hidden
address@hidden Locks}.
+This is a subcategory of @code{file-error}. @xref{File Locks}.
@c userlock.el
@item file-supersession
-This is a subcategory of @address@hidden
address@hidden Time}.
+This is a subcategory of @code{file-error}. @xref{Modification Time}.
@c net/ange-ftp.el
@item ftp-error
-This is a subcategory of @code{file-error}, which results from problems
-in accessing a remote file using address@hidden
address@hidden Files,,, emacs, The GNU Emacs Manual}.
+This is a subcategory of @code{file-error}, which results from
+problems in accessing a remote file using ftp. @xref{Remote Files,,,
+emacs, The GNU Emacs Manual}.
@item invalid-function
address@hidden"Invalid function"address@hidden
address@hidden Indirection}.
+The message is @samp{Invalid function}. @xref{Function Indirection}.
@item invalid-read-syntax
address@hidden"Invalid read syntax"address@hidden
address@hidden Representation}.
+The message is @samp{Invalid read syntax}. @xref{Printed
+Representation}.
@item invalid-regexp
address@hidden"Invalid regexp"address@hidden
address@hidden Expressions}.
+The message is @samp{Invalid regexp}. @xref{Regular Expressions}.
@c simple.el
@item mark-inactive
address@hidden"The mark is not active now"address@hidden
address@hidden Mark}.
+The message is @samp{The mark is not active now}. @xref{The Mark}.
@item no-catch
address@hidden"No catch for tag"address@hidden
address@hidden and Throw}.
+The message is @samp{No catch for tag}. @xref{Catch and Throw}.
@ignore
@c Not actually used for anything? Probably definition should be removed.
@item protected-field
address@hidden"Attempt to modify a protected field"}
+The message is @samp{Attempt to modify a protected fiel.
@end ignore
@item scan-error
address@hidden"Scan error"address@hidden
-This happens when certain syntax-parsing functions
-find invalid syntax or mismatched address@hidden
address@hidden Motion}, and @ref{Parsing Expressions}.
+The message is @samp{Scan error}. This happens when certain
+syntax-parsing functions find invalid syntax or mismatched
+parentheses. @xref{List Motion}, and @xref{Parsing Expressions}.
@item search-failed
address@hidden"Search failed"address@hidden
address@hidden and Matching}.
+The message is @samp{Search failed}. @xref{Searching and Matching}.
@item setting-constant
address@hidden"Attempt to set a constant symbol"address@hidden
-The values of the symbols @code{nil} and @code{t},
-and any symbols that start with @samp{:},
-may not be address@hidden
address@hidden Variables, , Variables that Never Change}.
+The message is @samp{Attempt to set a constant symbol}. This happens
+when attempting to assign values to @code{nil}, @code{t}, and keyword
+symbols. @xref{Constant Variables}.
@c simple.el
@item text-read-only
address@hidden"Text is read-only"address@hidden
-This is a subcategory of @address@hidden
address@hidden Properties}.
+The message is @samp{Text is read-only}. This is a subcategory of
address@hidden @xref{Special Properties}.
@item undefined-color
address@hidden"Undefined color"address@hidden
address@hidden Names}.
+The message is @samp{Undefined color}. @xref{Color Names}.
@item void-function
address@hidden"Symbol's function definition is void"address@hidden
+The message is @samp{Symbol's function definition is void}.
@xref{Function Cells}.
@item void-variable
address@hidden"Symbol's value as variable is void"address@hidden
+The message is @samp{Symbol's value as variable is void}.
@xref{Accessing Variables}.
@item wrong-number-of-arguments
address@hidden"Wrong number of arguments"address@hidden
address@hidden Lists}.
+The message is @samp{Wrong number of arguments}. @xref{Classifying
+Lists}.
@item wrong-type-argument
address@hidden"Wrong type argument"address@hidden
address@hidden Predicates}.
+The message is @samp{Wrong type argument}. @xref{Type Predicates}.
@end table
address@hidden The following seem to be unused now.
The following kinds of error, which are classified as special cases of
@code{arith-error}, can occur on certain systems for invalid use of
mathematical functions. @xref{Math Functions}.
@table @code
@item domain-error
address@hidden"Arithmetic domain error"}
+The message is @samp{Arithmetic domain error}.
@item overflow-error
address@hidden"Arithmetic overflow error"address@hidden
-This is a subcategory of @code{domain-error}.
+The message is @samp{Arithmetic overflow error}. This is a subcategory
+of @code{domain-error}.
@item range-error
address@hidden"Arithmetic range error"}
+The message is @code{Arithmetic range error}.
@item singularity-error
address@hidden"Arithmetic singularity error"address@hidden
-This is a subcategory of @code{domain-error}.
+The mssage is @samp{Arithmetic singularity error}. This is a
+subcategory of @code{domain-error}.
@item underflow-error
address@hidden"Arithmetic underflow error"address@hidden
-This is a subcategory of @code{domain-error}.
+The message is @samp{Arithmetic underflow error}. This is a
+subcategory of @code{domain-error}.
@end table
address@hidden ignore
=== modified file 'doc/lispref/frames.texi'
--- a/doc/lispref/frames.texi 2012-09-22 03:29:37 +0000
+++ b/doc/lispref/frames.texi 2012-09-30 09:18:38 +0000
@@ -1529,24 +1529,14 @@
@node Raising and Lowering
@section Raising and Lowering Frames
- Most window systems use a desktop metaphor. Part of this metaphor is
-the idea that windows are stacked in a notional third dimension
-perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest''. Where two windows overlap, the one higher up covers
-the one underneath. Even a window at the bottom of the stack can be
-seen if no other window overlaps it.
-
address@hidden @cindex raising a frame redundant with raise-frame
address@hidden raising a frame
@cindex lowering a frame
- A window's place in this ordering is not fixed; in fact, users tend
-to change the order frequently. @dfn{Raising} a window means moving
-it ``up'', to the top of the stack. @dfn{Lowering} a window means
-moving it to the bottom of the stack. This motion is in the notional
-third dimension only, and does not change the position of the window
-on the screen.
-
- With Emacs, frames constitute the windows in the metaphor sketched
-above. You can raise and lower frames using these functions:
+ Most window systems use a desktop metaphor. Part of this metaphor
+is the idea that system-level windows (e.g.@: Emacs frames) are
+stacked in a notional third dimension perpendicular to the screen
+surface. Where two overlap, the one higher up covers the one
+underneath. You can @dfn{raise} or @dfn{lower} a frame using the
+functions @code{raise-frame} and @code{lower-frame}.
@deffn Command raise-frame &optional frame
This function raises frame @var{frame} (default, the selected frame).
=== modified file 'doc/lispref/functions.texi'
--- a/doc/lispref/functions.texi 2012-08-07 03:33:37 +0000
+++ b/doc/lispref/functions.texi 2012-09-30 09:18:38 +0000
@@ -23,6 +23,7 @@
* Closures:: Functions that enclose a lexical environment.
* Obsolete Functions:: Declaring functions obsolete.
* Inline Functions:: Functions that the compiler will expand inline.
+* Declare Form:: Adding additional information about a function.
* Declaring Functions:: Telling the compiler that a function is defined.
* Function Safety:: Determining whether a function is safe to call.
* Related Topics:: Cross-references to specific Lisp primitives
@@ -521,7 +522,7 @@
is called @dfn{defining a function}, and it is done with the
@code{defun} special form.
address@hidden defun name argument-list body-forms...
address@hidden defun name argument-list body-forms...
@code{defun} is the usual way to define new Lisp functions. It
defines the symbol @var{name} as a function that looks like this:
@@ -578,7 +579,7 @@
from doing this, because redefining a function is sometimes done
deliberately, and there is no way to distinguish deliberate
redefinition from unintentional redefinition.
address@hidden defspec
address@hidden defmac
@cindex function aliases
@defun defalias name definition &optional docstring
@@ -1132,29 +1133,46 @@
@node Obsolete Functions
@section Declaring Functions Obsolete
-You can use @code{make-obsolete} to declare a function obsolete. This
-indicates that the function may be removed at some stage in the future.
+ You can mark a named function as @dfn{obsolete}, meaning that it may
+be removed at some point in the future. This causes Emacs to warn
+that the function is obsolete whenever it byte-compiles code
+containing that function, and whenever it displays the documentation
+for that function. In all other respects, an obsolete function
+behaves like any other function.
+
+ The easiest way to mark a function as obsolete is to put a
address@hidden(declare (obsolete @dots{}))} form in the function's
address@hidden definition. @xref{Declare Form}. Alternatively, you can
+use the @code{make-obsolete} function, described below.
+
+ A macro (@pxref{Macros}) can also be marked obsolete with
address@hidden; this has the same effects as for a function. An
+alias for a function or macro can also be marked as obsolete; this
+makes the alias itself obsolete, not the function or macro which it
+resolves to.
@defun make-obsolete obsolete-name current-name &optional when
-This function makes the byte compiler warn that the function
address@hidden is obsolete. If @var{current-name} is a symbol, the
-warning message says to use @var{current-name} instead of
address@hidden @var{current-name} does not need to be an alias for
address@hidden; it can be a different function with similar
-functionality. If @var{current-name} is a string, it is the warning
-message.
+This function marks @var{obsolete-name} as obsolete.
address@hidden should be a symbol naming a function or macro, or
+an alias for a function or macro.
+
+If @var{current-name} is a symbol, the warning message says to use
address@hidden instead of @var{obsolete-name}. @var{current-name}
+does not need to be an alias for @var{obsolete-name}; it can be a
+different function with similar functionality. @var{current-name} can
+also be a string, which serves as the warning message. The message
+should begin in lower case, and end with a period. It can also be
address@hidden, in which case the warning message provides no additional
+details.
If provided, @var{when} should be a string indicating when the function
was first made obsolete---for example, a date or a release number.
@end defun
-You can define a function as an alias and declare it obsolete at the
-same time using the macro @code{define-obsolete-function-alias}:
-
@defmac define-obsolete-function-alias obsolete-name current-name &optional
when docstring
-This macro marks the function @var{obsolete-name} obsolete and also
-defines it as an alias for the function @var{current-name}. It is
-equivalent to the following:
+This convenience macro marks the function @var{obsolete-name} obsolete
+and also defines it as an alias for the function @var{current-name}.
+It is equivalent to the following:
@example
(defalias @var{obsolete-name} @var{current-name} @var{docstring})
@@ -1236,6 +1254,63 @@
After an inline function is defined, its inline expansion can be
performed later on in the same file, just like macros.
address@hidden Declare Form
address@hidden The @code{declare} Form
address@hidden declare
+
+ @code{declare} is a special macro which can be used to add ``meta''
+properties to a function or macro: for example, marking it as
+obsolete, or giving its forms a special @key{TAB} indentation
+convention in Emacs Lisp mode.
+
address@hidden of declare}
address@hidden declare @address@hidden
+This macro ignores its arguments and evaluates to @code{nil}; it has
+no run-time effect. However, when a @code{declare} form occurs as the
address@hidden first form} in the body of a @code{defun} function
+definition or a @code{defmacro} macro definition (@pxref{Defining
+Macros}, for a description of @code{defmacro}), it appends the
+properties specified by @var{specs} to the function or macro. This
+work is specially performed by the @code{defun} and @code{defmacro}
+macros.
+
+Note that if you put a @code{declare} form in an interactive function,
+it should go before the @code{interactive} form.
+
+Each element in @var{specs} should have the form @code{(@var{property}
address@hidden@dots{})}, which should not be quoted. These have the
+following effects:
+
address@hidden @code
address@hidden (advertised-calling-convention @var{signature} @var{when})
+This acts like a call to @code{set-advertised-calling-convention}
+(@pxref{Obsolete Functions}); @var{signature} specifies the correct
+argument list for calling the function or macro, and @var{when} should
+be a string indicating when the variable was first made obsolete.
+
address@hidden (debug @var{edebug-form-spec})
+This is valid for macros only. When stepping through the macro with
+Edebug, use @var{edebug-form-spec}. @xref{Instrumenting Macro Calls}.
+
address@hidden (doc-string @var{n})
+Use element number @var{n}, if any, as the documentation string.
+
address@hidden (indent @var{indent-spec})
+Indent calls to this function or macro according to @var{indent-spec}.
+This is typically used for macros, though it works for functions too.
address@hidden Macros}.
+
address@hidden (obsolete @var{current-name} @var{when})
+Mark the function or macro as obsolete, similar to a call to
address@hidden (@pxref{Obsolete Functions}). @var{current-name}
+should be a symbol (in which case the warning message says to use that
+instead), a string (specifying the warning message), or @code{nil} (in
+which case the warning message gives no extra details). @var{when}
+should be a string indicating when the function or macro was first
+made obsolete.
address@hidden table
address@hidden defmac
+
@node Declaring Functions
@section Telling the Compiler that a Function is Defined
@cindex function declaration
=== modified file 'doc/lispref/help.texi'
--- a/doc/lispref/help.texi 2012-05-27 01:34:14 +0000
+++ b/doc/lispref/help.texi 2012-09-30 09:18:38 +0000
@@ -58,11 +58,17 @@
are many other conventions for documentation strings; see
@ref{Documentation Tips}.
- Documentation strings can contain several special substrings, which
-stand for key bindings to be looked up in the current keymaps when the
-documentation is displayed. This allows documentation strings to refer
-to the keys for related commands and be accurate even when a user
-rearranges the key bindings. (@xref{Keys in Documentation}.)
+ Documentation strings can contain several special text sequences,
+referring to key bindings which are looked up in the current keymaps
+when the user views the documentation. This allows the help commands
+to display the correct keys even if a user rearranges the default key
+bindings. @xref{Keys in Documentation}.
+
+ In the documentation string of an autoloaded command
+(@pxref{Autoload}), these special text sequences have an additional
+special effect: they cause @kbd{C-h f} (@code{describe-function}) on
+the command to trigger autoloading. (This is needed for correctly
+setting up the hyperlinks in the @file{*Help*} buffer).
@vindex emacs-lisp-docstring-fill-column
Emacs Lisp mode fills documentation strings to the width
=== modified file 'doc/lispref/loading.texi'
--- a/doc/lispref/loading.texi 2012-07-07 09:51:59 +0000
+++ b/doc/lispref/loading.texi 2012-09-30 09:18:38 +0000
@@ -384,11 +384,13 @@
@section Autoload
@cindex autoload
- The @dfn{autoload} facility allows you to register the existence of
-a function or macro, but put off loading the file that defines it.
-The first call to the function automatically reads the proper file, in
+ The @dfn{autoload} facility lets you register the existence of a
+function or macro, but put off loading the file that defines it. The
+first call to the function automatically loads the proper library, in
order to install the real definition and other associated code, then
runs the real definition as if it had been loaded all along.
+Autoloading can also be triggered by looking up the documentation of
+the function or macro (@pxref{Documentation Basics}).
There are two ways to set up an autoloaded function: by calling
@code{autoload}, and by writing a special ``magic'' comment in the
=== modified file 'doc/lispref/macros.texi'
--- a/doc/lispref/macros.texi 2012-06-18 15:57:41 +0000
+++ b/doc/lispref/macros.texi 2012-09-30 09:18:38 +0000
@@ -235,43 +235,8 @@
@end example
The body of a macro definition can include a @code{declare} form,
-which can specify how @key{TAB} should indent macro calls, and how to
-step through them for Edebug.
-
address@hidden declare @address@hidden
address@hidden of declare}
-A @code{declare} form is used in a macro definition to specify various
-additional information about it. The following specifications are
-currently supported:
-
address@hidden @code
address@hidden (debug @var{edebug-form-spec})
-Specify how to step through macro calls for Edebug.
address@hidden Macro Calls}.
-
address@hidden (indent @var{indent-spec})
-Specify how to indent calls to this macro. @xref{Indenting Macros},
-for more details.
-
address@hidden (doc-string @var{number})
-Specify which element of the macro is the documentation string, if
-any.
address@hidden table
-
-A @code{declare} form only has its special effect in the body of a
address@hidden form if it immediately follows the documentation
-string, if present, or the argument list otherwise. (Strictly
-speaking, @emph{several} @code{declare} forms can follow the
-documentation string or argument list, but since a @code{declare} form
-can have several @var{specs}, they can always be combined into a
-single form.) When used at other places in a @code{defmacro} form, or
-outside a @code{defmacro} form, @code{declare} just returns @code{nil}
-without evaluating any @var{specs}.
address@hidden defmac
-
- No macro absolutely needs a @code{declare} form, because that form
-has no effect on how the macro expands, on what the macro means in the
-program. It only affects the secondary features listed above.
+which specifies additional properties about the macro. @xref{Declare
+Form}.
@node Problems with Macros
@section Common Problems Using Macros
=== modified file 'doc/lispref/numbers.texi'
--- a/doc/lispref/numbers.texi 2012-09-11 02:28:27 +0000
+++ b/doc/lispref/numbers.texi 2012-09-30 09:18:38 +0000
@@ -48,9 +48,8 @@
@tex
@math{2^{29}-1}),
@end tex
-but some machines provide a wider range. Many examples in this
-chapter assume that an integer has 30 bits and that floating point
-numbers are IEEE double precision.
+but many machines provide a wider range. Many examples in this
+chapter assume the minimum integer width of 30 bits.
@cindex overflow
The Lisp reader reads an integer as a sequence of digits with optional
@@ -160,8 +159,9 @@
handle. It is negative.
@end defvar
- @xref{Character Codes, max-char}, for the maximum value of a valid
-character codepoint.
+ In Emacs Lisp, text characters are represented by integers. Any
+integer between zero and the value of @code{max-char}, inclusive, is
+considered to be valid as a character. @xref{String Basics}.
@node Float Basics
@section Floating Point Basics
@@ -171,8 +171,8 @@
not integral. The precise range of floating point numbers is
machine-specific; it is the same as the range of the C data type
@code{double} on the machine you are using. Emacs uses the
address@hidden floating point standard where possible (the standard is
-supported by most modern computers).
address@hidden floating point standard, which is supported by all
+modern computers.
The read syntax for floating point numbers requires either a decimal
point (with at least one digit following), an exponent, or both. For
@@ -316,17 +316,16 @@
@emph{object}. By contrast, @code{=} compares only the numeric values
of the objects.
- At present, each integer value has a unique Lisp object in Emacs Lisp.
+ In Emacs Lisp, each integer value is a unique Lisp object.
Therefore, @code{eq} is equivalent to @code{=} where integers are
-concerned. It is sometimes convenient to use @code{eq} for comparing an
-unknown value with an integer, because @code{eq} does not report an
-error if the unknown value is not a number---it accepts arguments of any
-type. By contrast, @code{=} signals an error if the arguments are not
-numbers or markers. However, it is a good idea to use @code{=} if you
-can, even for comparing integers, just in case we change the
-representation of integers in a future Emacs version.
+concerned. It is sometimes convenient to use @code{eq} for comparing
+an unknown value with an integer, because @code{eq} does not report an
+error if the unknown value is not a number---it accepts arguments of
+any type. By contrast, @code{=} signals an error if the arguments are
+not numbers or markers. However, it is better programming practice to
+use @code{=} if you can, even for comparing integers.
- Sometimes it is useful to compare numbers with @code{equal}; it
+ Sometimes it is useful to compare numbers with @code{equal}, which
treats two numbers as equal if they have the same data type (both
integers, or both floating point) and the same value. By contrast,
@code{=} can treat an integer and a floating point number as equal.
@@ -439,15 +438,16 @@
it unchanged.
@end defun
-There are four functions to convert floating point numbers to integers;
-they differ in how they round. All accept an argument @var{number}
-and an optional argument @var{divisor}. Both arguments may be
-integers or floating point numbers. @var{divisor} may also be
+ There are four functions to convert floating point numbers to
+integers; they differ in how they round. All accept an argument
address@hidden and an optional argument @var{divisor}. Both arguments
+may be integers or floating point numbers. @var{divisor} may also be
@code{nil}. If @var{divisor} is @code{nil} or omitted, these
functions convert @var{number} to an integer, or return it unchanged
if it already is an integer. If @var{divisor} is address@hidden, they
divide @var{number} by @var{divisor} and convert the result to an
-integer. An @code{arith-error} results if @var{divisor} is 0.
+integer. integer. If @var{divisor} is zero (whether integer or
+floating-point), Emacs signals an @code{arith-error} error.
@defun truncate number &optional divisor
This returns @var{number}, converted to an integer by rounding towards
@@ -524,14 +524,12 @@
@section Arithmetic Operations
@cindex arithmetic operations
- Emacs Lisp provides the traditional four arithmetic operations:
-addition, subtraction, multiplication, and division. Remainder and modulus
-functions supplement the division functions. The functions to
-add or subtract 1 are provided because they are traditional in Lisp and
-commonly used.
-
- All of these functions except @code{%} return a floating point value
-if any argument is floating.
+ Emacs Lisp provides the traditional four arithmetic operations
+(addition, subtraction, multiplication, and division), as well as
+remainder and modulus functions, and functions to add or subtract 1.
+Except for @code{%}, each of these functions accepts both integer and
+floating point arguments, and returns a floating point number if any
+argument is a floating point number.
It is important to note that in Emacs Lisp, arithmetic functions
do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to
@@ -620,40 +618,49 @@
divides @var{dividend} by each divisor in turn. Each argument may be a
number or a marker.
-If all the arguments are integers, then the result is an integer too.
-This means the result has to be rounded. On most machines, the result
-is rounded towards zero after each division, but some machines may round
-differently with negative arguments. This is because the Lisp function
address@hidden/} is implemented using the C division operator, which also
-permits machine-dependent rounding. As a practical matter, all known
-machines round in the standard fashion.
-
address@hidden @code{arith-error} in division
-If you divide an integer by 0, an @code{arith-error} error is signaled.
-(@xref{Errors}.) Floating point division by zero returns either
-infinity or a NaN if your machine supports @acronym{IEEE} floating point;
-otherwise, it signals an @code{arith-error} error.
+If all the arguments are integers, the result is an integer, obtained
+by rounding the quotient towards zero after each division.
+(Hypothetically, some machines may have different rounding behavior
+for negative arguments, because @code{/} is implemented using the C
+division operator, which permits machine-dependent rounding; but this
+does not happen in practice.)
@example
@group
(/ 6 2)
@result{} 3
@end group
address@hidden
(/ 5 2)
@result{} 2
address@hidden group
address@hidden
(/ 5.0 2)
@result{} 2.5
address@hidden group
address@hidden
(/ 5 2.0)
@result{} 2.5
address@hidden group
address@hidden
(/ 5.0 2.0)
@result{} 2.5
address@hidden group
address@hidden
(/ 25 3 2)
@result{} 4
address@hidden group
@group
(/ -17 6)
- @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
+ @result{} -2
@end group
@end example
+
address@hidden @code{arith-error} in division
+If you divide an integer by the integer 0, Emacs signals an
address@hidden error (@pxref{Errors}). If you divide a floating
+point number by 0, or divide by the floating point number 0.0, the
+result is either positive or negative infinity (@pxref{Float Basics}).
@end defun
@defun % dividend divisor
@@ -661,10 +668,18 @@
This function returns the integer remainder after division of @var{dividend}
by @var{divisor}. The arguments must be integers or markers.
-For negative arguments, the remainder is in principle machine-dependent
-since the quotient is; but in practice, all known machines behave alike.
-
-An @code{arith-error} results if @var{divisor} is 0.
+For any two integers @var{dividend} and @var{divisor},
+
address@hidden
address@hidden
+(+ (% @var{dividend} @var{divisor})
+ (* (/ @var{dividend} @var{divisor}) @var{divisor}))
address@hidden group
address@hidden example
+
address@hidden
+always equals @var{dividend}. If @var{divisor} is zero, Emacs signals
+an @code{arith-error} error.
@example
(% 9 4)
@@ -676,18 +691,6 @@
(% -9 -4)
@result{} -1
@end example
-
-For any two integers @var{dividend} and @var{divisor},
-
address@hidden
address@hidden
-(+ (% @var{dividend} @var{divisor})
- (* (/ @var{dividend} @var{divisor}) @var{divisor}))
address@hidden group
address@hidden example
-
address@hidden
-always equals @var{dividend}.
@end defun
@defun mod dividend divisor
@@ -697,10 +700,9 @@
by @var{divisor}, but with the same sign as @var{divisor}.
The arguments must be numbers or markers.
-Unlike @code{%}, @code{mod} returns a well-defined result for negative
-arguments. It also permits floating point arguments; it rounds the
-quotient downward (towards minus infinity) to an integer, and uses that
-quotient to compute the remainder.
+Unlike @code{%}, @code{mod} permits floating point arguments; it
+rounds the quotient downward (towards minus infinity) to an integer,
+and uses that quotient to compute the remainder.
If @var{divisor} is zero, @code{mod} signals an @code{arith-error}
error if both arguments are integers, and returns a NaN otherwise.
@@ -1086,8 +1088,8 @@
@defun sin arg
@defunx cos arg
@defunx tan arg
-These are the ordinary trigonometric functions, with argument measured
-in radians.
+These are the basic trigonometric functions, with argument @var{arg}
+measured in radians.
@end defun
@defun asin arg
@@ -1154,20 +1156,6 @@
returns a NaN.
@end defun
address@hidden
address@hidden expm1 arg
-This function returns @code{(1- (exp @var{arg}))}, but it is more
-accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
-is close to 1.
address@hidden defun
-
address@hidden log1p arg
-This function returns @code{(log (1+ @var{arg}))}, but it is more
-accurate than that when @var{arg} is so small that adding 1 to it would
-lose accuracy.
address@hidden defun
address@hidden ignore
-
@defun log10 arg
This function returns the logarithm of @var{arg}, with base 10:
@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}.
@@ -1201,20 +1189,20 @@
@section Random Numbers
@cindex random numbers
-A deterministic computer program cannot generate true random numbers.
-For most purposes, @dfn{pseudo-random numbers} suffice. A series of
-pseudo-random numbers is generated in a deterministic fashion. The
-numbers are not truly random, but they have certain properties that
-mimic a random series. For example, all possible values occur equally
-often in a pseudo-random series.
-
-In Emacs, pseudo-random numbers are generated from a ``seed''.
-Starting from any given seed, the @code{random} function always
-generates the same sequence of numbers. Emacs typically starts with a
-different seed each time, so the sequence of values of @code{random}
-typically differs in each Emacs run.
-
-Sometimes you want the random number sequence to be repeatable. For
+ A deterministic computer program cannot generate true random
+numbers. For most purposes, @dfn{pseudo-random numbers} suffice. A
+series of pseudo-random numbers is generated in a deterministic
+fashion. The numbers are not truly random, but they have certain
+properties that mimic a random series. For example, all possible
+values occur equally often in a pseudo-random series.
+
+ Pseudo-random numbers are generated from a ``seed''. Starting from
+any given seed, the @code{random} function always generates the same
+sequence of numbers. By default, Emacs initializes the random seed at
+startup, in such a way that the sequence of values of @code{random}
+(with overwhelming likelihood) differs in each Emacs run.
+
+ Sometimes you want the random number sequence to be repeatable. For
example, when debugging a program whose behavior depends on the random
number sequence, it is helpful to get the same behavior in each
program run. To make the sequence repeat, execute @code{(random "")}.
@@ -1227,8 +1215,10 @@
series of pseudo-random integers.
If @var{limit} is a positive integer, the value is chosen to be
-nonnegative and less than @var{limit}. Otherwise, the value
-might be any integer representable in Lisp.
+nonnegative and less than @var{limit}. Otherwise, the value might be
+any integer representable in Lisp, i.e.@: an integer between
address@hidden and @code{most-positive-fixnum}
+(@pxref{Integer Basics}).
If @var{limit} is @code{t}, it means to choose a new seed based on the
current time of day and on Emacs's process @acronym{ID} number.
=== modified file 'doc/lispref/os.texi'
--- a/doc/lispref/os.texi 2012-09-22 13:16:03 +0000
+++ b/doc/lispref/os.texi 2012-09-30 09:18:38 +0000
@@ -70,13 +70,11 @@
automatically when Emacs is installed.
@item
-It registers input methods by loading any @file{leim-list.el} file
-found in the @code{load-path}.
-
address@hidden It removes PWD from the environment if it is not accurate.
address@hidden It abbreviates default-directory.
-
address@hidden Now normal-top-level calls command-line.
+If the library @file{leim-list.el} exists, Emacs loads it. This
+optional library is intended for registering input methods; Emacs
+looks for it in @code{load-path} (@pxref{Library Search}), skipping
+those directories containing the standard Emacs libraries (since
address@hidden should not exist in those directories).
@vindex before-init-time
@item
@@ -1159,6 +1157,20 @@
The value may be a floating point number.
@end defun
address@hidden system-users
+This function returns a list of strings, listing the user names on the
+system. If Emacs cannot retrieve this information, the return value
+is a list containing just the value of @code{user-real-login-name}.
address@hidden defun
+
address@hidden user groups
address@hidden system-groups
+This function returns a list of strings, listing the names of user
+groups on the system. If Emacs cannot retrieve this information, the
+return value is @code{nil}.
address@hidden defun
+
+
@node Time of Day
@section Time of Day
@@ -1812,6 +1824,29 @@
input. Then it becomes idle again, and all the idle timers that are
set up to repeat will subsequently run another time, one by one.
+ Do not write an idle timer function containing a loop which does a
+certain amount of processing each time around, and exits when
address@hidden(input-pending-p)} is address@hidden This approach seems very
+natural but has two problems:
+
address@hidden
address@hidden
+It blocks out all process output (since Emacs accepts process output
+only while waiting).
+
address@hidden
+It blocks out any idle timers that ought to run during that time.
address@hidden itemize
+
address@hidden
+Similarly, do not write an idle timer function that sets up another
+idle timer (including the same idle timer) with @var{secs} argument
+less than or equal to the current idleness time. Such a timer will
+run almost immediately, and continue running again and again, instead
+of waiting for the next time Emacs becomes idle. The correct approach
+is to reschedule with an appropriate increment of the current value of
+the idleness time, as described below.
+
@defun current-idle-time
If Emacs is idle, this function returns the length of time Emacs has
been idle, as a list of four integers: @code{(@var{sec-high}
@@ -1820,60 +1855,34 @@
When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
This is a convenient way to test whether Emacs is idle.
-
-The main use of this function is when an idle timer function wants to
-``take a break'' for a while. It can set up another idle timer to
-call the same function again, after a few seconds more idleness.
-Here's an example:
-
address@hidden
-(defvar resume-timer nil
- "Timer that `timer-function' used to reschedule itself, or nil.")
-
-(defun timer-function ()
- ;; @r{If the user types a command while @code{resume-timer}}
address@hidden defun
+
+ The main use of @code{current-idle-time} is when an idle timer
+function wants to ``take a break'' for a while. It can set up another
+idle timer to call the same function again, after a few seconds more
+idleness. Here's an example:
+
address@hidden
+(defvar my-resume-timer nil
+ "Timer for `my-timer-function' to reschedule itself, or nil.")
+
+(defun my-timer-function ()
+ ;; @r{If the user types a command while @code{my-resume-timer}}
;; @r{is active, the next time this function is called from}
- ;; @r{its main idle timer, deactivate @code{resume-timer}.}
- (when resume-timer
- (cancel-timer resume-timer))
+ ;; @r{its main idle timer, deactivate @code{my-resume-timer}.}
+ (when my-resume-timer
+ (cancel-timer my-resume-timer))
address@hidden the work for a while}...
(when @var{taking-a-break}
- (setq resume-timer
+ (setq my-resume-timer
(run-with-idle-timer
;; Compute an idle time @var{break-length}
;; more than the current value.
(time-add (current-idle-time)
(seconds-to-time @var{break-length}))
nil
- 'timer-function))))
address@hidden smallexample
address@hidden defun
-
- Do not write an idle timer function containing a loop which does a
-certain amount of processing each time around, and exits when
address@hidden(input-pending-p)} is address@hidden This approach seems very
-natural but has two problems:
-
address@hidden
address@hidden
-It blocks out all process output (since Emacs accepts process output
-only while waiting).
-
address@hidden
-It blocks out any idle timers that ought to run during that time.
address@hidden itemize
-
address@hidden
-For similar reasons, do not write an idle timer function that sets
-up another idle time (including the same idle timer) with the
address@hidden argument less or equal to the current idleness time. Such
-a timer will run almost immediately, and continue running again and
-again, instead of waiting for the next time Emacs becomes idle.
-
address@hidden
-The correct approach is for the idle timer to reschedule itself after
-a brief pause, using the method in the @code{timer-function} example
-above.
+ 'my-timer-function))))
address@hidden example
@node Terminal Input
@section Terminal Input
@@ -1907,7 +1916,6 @@
(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
has no effect except in @sc{cbreak} mode.
address@hidden Emacs 19 feature
The argument @var{meta} controls support for input character codes
above 127. If @var{meta} is @code{t}, Emacs converts characters with
the 8th bit set into Meta characters. If @var{meta} is @code{nil},
@@ -1916,7 +1924,6 @@
Emacs uses all 8 bits of input unchanged. This is good for terminals
that use 8-bit character sets.
address@hidden Emacs 19 feature
If @var{quit-char} is address@hidden, it specifies the character to
use for quitting. Normally this character is @kbd{C-g}.
@xref{Quitting}.
@@ -1925,7 +1932,6 @@
The @code{current-input-mode} function returns the input mode settings
Emacs is currently using.
address@hidden Emacs 19 feature
@defun current-input-mode
This function returns the current mode for reading keyboard input. It
returns a list, corresponding to the arguments of @code{set-input-mode},
=== modified file 'doc/lispref/strings.texi'
--- a/doc/lispref/strings.texi 2012-05-27 01:34:14 +0000
+++ b/doc/lispref/strings.texi 2012-09-30 09:18:38 +0000
@@ -35,28 +35,31 @@
@node String Basics
@section String and Character Basics
- Characters are represented in Emacs Lisp as integers;
-whether an integer is a character or not is determined only by how it is
-used. Thus, strings really contain integers. @xref{Character Codes},
-for details about character representation in Emacs.
+ A character is a Lisp object which represents a single character of
+text. In Emacs Lisp, characters are simply integers; whether an
+integer is a character or not is determined only by how it is used.
address@hidden Codes}, for details about character representation in
+Emacs.
- The length of a string (like any array) is fixed, and cannot be
-altered once the string exists. Strings in Lisp are @emph{not}
-terminated by a distinguished character code. (By contrast, strings in
-C are terminated by a character with @acronym{ASCII} code 0.)
+ A string is a fixed sequence of characters. It is a type of
+sequence called a @dfn{array}, meaning that its length is fixed and
+cannot be altered once it is created (@pxref{Sequences Arrays
+Vectors}). Unlike in C, Emacs Lisp strings are @emph{not} terminated
+by a distinguished character code.
Since strings are arrays, and therefore sequences as well, you can
-operate on them with the general array and sequence functions.
-(@xref{Sequences Arrays Vectors}.) For example, you can access or
-change individual characters in a string using the functions @code{aref}
-and @code{aset} (@pxref{Array Functions}). However, note that
address@hidden should @emph{not} be used for computing the width of a
-string on display; use @code{string-width} (@pxref{Width}) instead.
+operate on them with the general array and sequence functions
+documented in @ref{Sequences Arrays Vectors}. For example, you can
+access or change individual characters in a string using the functions
address@hidden and @code{aset} (@pxref{Array Functions}). However, note
+that @code{length} should @emph{not} be used for computing the width
+of a string on display; use @code{string-width} (@pxref{Width})
+instead.
- There are two text representations for address@hidden characters in
-Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
-Representations}). For most Lisp programming, you don't need to be
-concerned with these two representations.
+ There are two text representations for address@hidden
+characters in Emacs strings (and in buffers): unibyte and multibyte.
+For most Lisp programming, you don't need to be concerned with these
+two representations. @xref{Text Representations}, for details.
Sometimes key sequences are represented as unibyte strings. When a
unibyte string is a key sequence, string elements in the range 128 to
@@ -88,7 +91,7 @@
representations and to encode and decode character codes.
@node Predicates for Strings
address@hidden The Predicates for Strings
address@hidden Predicates for Strings
For more information about general sequence and array predicates,
see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
=== modified file 'etc/NEWS'
--- a/etc/NEWS 2012-09-30 09:10:59 +0000
+++ b/etc/NEWS 2012-09-30 09:18:38 +0000
@@ -76,6 +76,7 @@
* Startup Changes in Emacs 24.3
++++
** Emacs no longer searches for `leim-list.el' files beneath the standard
lisp/ directory. There should not be any there anyway. If you have
been adding them there, put them somewhere else, eg site-lisp.
@@ -89,10 +90,12 @@
** minibuffer-electric-default-mode can rewrite (default ...) to [...].
Just set minibuffer-eldef-shorten-default to t before enabling the mode.
++++
** Most y-or-n prompts now allow you to scroll the selected window.
Typing C-v or M-v at a y-or-n prompt scrolls forward or backward
respectively, without exiting from the prompt.
+---
** In minibuffer filename prompts, `C-M-f' and `C-M-b' now move to the
next and previous path separator, respectively.
@@ -107,12 +110,14 @@
** Help changes
++++
*** `C-h f' (describe-function) can now perform autoloading.
When this command is called for an autoloaded function whose docstring
contains a key substitution construct, that function's library is
automatically loaded, so that the documentation can be shown
correctly. To disable this, set `help-enable-auto-load' to nil.
+---
*** `C-h f' now reports previously-autoloaded functions as "autoloaded",
even after their associated libraries have been loaded (and the
autoloads have been redefined as functions).
@@ -136,11 +141,11 @@
:background image spec property.
** Server and client changes
-
++++
*** emacsclient now obeys string values for `initial-buffer-choice',
if it is told to open a new frame without specifying any file to visit
or expression to evaluate.
-
+---
*** New option `server-auth-key' specifies a shared server key.
** In the Package Menu, newly-available packages are listed as "new",
@@ -155,6 +160,7 @@
of the fatal signal, and a short backtrace on platforms like glibc
that support backtraces.
+---
** If your Emacs was built from a bzr checkout, the new variable
`emacs-bzr-version' contains information about the bzr revision used.
@@ -185,38 +191,25 @@
* Editing Changes in Emacs 24.3
** Navigation command changes
-
++++
*** New binding `M-g c' for `goto-char'.
-
++++
*** New binding `M-g TAB' for `move-to-column'.
-
++++
*** `M-g TAB' (`move-to-column') prompts for a column number if called
interactively with no prefix arg. Previously, it moved to column 1.
-+++
-** `C-x 8 RET' is now bound to `insert-char', which is now a command.
-`ucs-insert' is now an obsolete alias for `insert-char'.
-
----
-** The `z' key no longer has a binding in most special modes.
-It used to be bound to `kill-this-buffer', but `z' is too easy to
-accidentally type.
-
-** New option `delete-trailing-lines' specifies whether
-M-x delete-trailing-whitespace should delete trailing lines at the end
-of the buffer. It defaults to t.
-
** Search and Replace changes
-
++++
*** Non-regexp Isearch now performs "lax" space matching.
Each sequence of spaces in the supplied search string may match any
sequence of one or more whitespace characters, as specified by the
variable `search-whitespace-regexp'. (This variable is also used by a
similar existing feature for regexp Isearch).
-
++++
*** New Isearch command `M-s SPC' toggles lax space matching.
This applies to both ordinary and regexp Isearch.
-
++++
*** New option `replace-lax-whitespace'.
If non-nil, `query-replace' uses flexible whitespace matching too.
The default is nil.
@@ -225,6 +218,20 @@
and `M-s _' in Isearch toggles symbol search mode.
`M-s c' in Isearch toggles search case-sensitivity.
++++
+** `C-x 8 RET' is now bound to `insert-char', which is now a command.
+`ucs-insert' is now an obsolete alias for `insert-char'.
+
+---
+** The `z' key no longer has a binding in most special modes.
+It used to be bound to `kill-this-buffer', but `z' is too easy to
+accidentally type.
+
++++
+** New option `delete-trailing-lines' specifies whether
+M-x delete-trailing-whitespace should delete trailing lines at the end
+of the buffer. It defaults to t.
+
** Register changes
+++
*** `C-x r +' is now overloaded to invoke `append-to-register.
@@ -233,8 +240,10 @@
the text to put between collected texts for use with M-x
append-to-register and M-x prepend-to-register.
++++
** `C-u M-=' now counts lines/words/characters in the entire buffer.
++++
** New command `C-x r M-w' (copy-rectangle-as-kill).
It copies the region-rectangle as the last rectangle kill.
@@ -246,17 +255,17 @@
* Changes in Specialized Modes and Packages in Emacs 24.3
** Apropos
-
+---
*** The faces used by Apropos are now directly customizable.
These faces are named `apropos-symbol', `apropos-keybinding', and so on;
see the `apropos' Custom group for details.
-
-**** The old options whose values specified faces to use were removed
+---
+*** The old options whose values specified faces to use were removed
(i.e. `apropos-symbol-face', `apropos-keybinding-face', etc.).
** Buffer Menu
This package has been rewritten to use Tabulated List mode.
-
+---
*** Option `Buffer-menu-buffer+size-width' is now obsolete.
Use `Buffer-menu-name-width' and `Buffer-menu-size-width' instead.
@@ -580,22 +589,22 @@
** Obsolete packages:
-
++++
*** assoc.el
In most cases, assoc+member+push+delq work just as well.
And in any case it's just a terrible package: ugly semantics, terrible
inefficiency, and not namespace-clean.
-
+---
*** bruce.el
-
+---
*** ledit.el
-
+---
*** mailpost.el
-
++++
*** mouse-sel.el
-
+---
*** patcomp.el
-
++++
*** cust-print.el
@@ -603,11 +612,13 @@
* Incompatible Lisp Changes in Emacs 24.3
++++
** (random) by default now returns a different random sequence in
every Emacs run. Use (random S), where S is a string, to set the
random seed to a value based on S, in order to get a repeatable
sequence in later calls.
+---
** The function `x-select-font' can return a font spec, instead of a
font name as a string. Whether it returns a font spec or a font name
depends on the graphical library.
@@ -628,6 +639,7 @@
defmacro currently return the name of the newly defined function/macro
but this should not be relied upon.
+---
** `face-spec-set' no longer sets frame-specific attributes when the
third argument is a frame (that usage was obsolete since Emacs 22.2).
@@ -772,23 +784,24 @@
**** `display-buffer-function'
** Time
-
+---
*** `current-time-string' no longer requires that its argument's year
must be in the range 1000..9999. It now works with any year supported
by the underlying C implementation.
-
+---
*** `current-time' now returns extended-format time stamps
(HIGH LOW USEC PSEC), where the new PSEC slot specifies picoseconds.
PSEC is typically a multiple of 1000 on current machines. Other
functions that use this format, such as file-attributes and
format-time-string, have been changed accordingly. Old-format time
stamps are still accepted.
-
+---
*** The format of timers in timer-list and timer-idle-list is now
[TRIGGERED-P HI-SECS LO-SECS USECS REPEAT-DELAY FUNCTION ARGS IDLE-DELAY
PSECS].
The PSECS slot is new, and uses picosecond resolution. It can be
accessed via the new timer--psecs accessor.
++++
** Floating point functions now always return special values like NaN,
instead of signaling errors, if given invalid args, e.g. (log -1.0).
Previously, they returned NaNs on some platforms but signaled errors
@@ -806,18 +819,22 @@
*** `autoloadp'
*** `autoload-do-load'.
++++
*** `buffer-narrowed-p' tests if the buffer is narrowed.
*** `file-name-base' returns a file name sans directory and extension.
*** `function-get' fetches a function property, following aliases.
++++
*** `posnp' tests if an object is a `posn'.
*** `set-temporary-overlay-map' sets up a temporary overlay map.
++++
*** `system-users' returns the user names on the system.
++++
*** `system-groups' returns the group names on the system.
*** `tty-top-frame' returns the topmost frame of a text terminal.
** New macros `setq-local' and `defvar-local'.
-** New fringe bitmap exclamation-mark.
+** New fringe bitmap `exclamation-mark'.
** Face underlining can now use a wave.
See the "Face Attributes" section of the Elisp manual.
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2012-09-30 09:10:59 +0000
+++ b/lisp/ChangeLog 2012-09-30 09:18:38 +0000
@@ -34,6 +34,13 @@
2012-09-30 Chong Yidong <address@hidden>
+ * server.el (server-host): Document the security implications.
+ (server-auth-key): Doc fix.
+
+ * startup.el (initial-buffer-choice): Doc fix.
+
+ * minibuffer.el (minibuffer-local-filename-syntax): Doc fix.
+
* simple.el (delete-trailing-whitespace): Avoid an unnecessary
restriction change.
=== modified file 'lisp/minibuffer.el'
--- a/lisp/minibuffer.el 2012-09-11 17:43:21 +0000
+++ b/lisp/minibuffer.el 2012-09-30 09:18:38 +0000
@@ -2332,7 +2332,7 @@
(modify-syntax-entry c "." table))
'(?/ ?: ?\\))
table)
- "Syntax table to be used in minibuffer for reading file name.")
+ "Syntax table used when reading a file name in the minibuffer.")
;; minibuffer-completing-file-name is a variable used internally in minibuf.c
;; to determine whether to use minibuffer-local-filename-completion-map or
=== modified file 'lisp/server.el'
--- a/lisp/server.el 2012-09-01 01:04:26 +0000
+++ b/lisp/server.el 2012-09-30 09:18:38 +0000
@@ -101,7 +101,12 @@
(defcustom server-host nil
"The name or IP address to use as host address of the server process.
-If set, the server accepts remote connections; otherwise it is local."
+If set, the server accepts remote connections; otherwise it is local.
+
+DO NOT give this a non-nil value unless you know what you are
+doing! On unsecured networks, accepting remote connections is
+very dangerous, because server-client communication (including
+session authentication) is not encrypted."
:group 'server
:type '(choice
(string :tag "Name or IP address")
@@ -140,12 +145,12 @@
(defcustom server-auth-key nil
"Server authentication key.
+This is only used if `server-use-tcp' is non-nil.
Normally, the authentication key is randomly generated when the
-server starts, which guarantees some level of security. It is
-recommended to leave it that way. Using a long-lived shared key
-will decrease security (especially since the key is transmitted as
-plain text).
+server starts. It is recommended to leave it that way. Using a
+long-lived shared key will decrease security (especially since
+the key is transmitted as plain-text).
In some situations however, it can be difficult to share randomly
generated passwords with remote hosts (eg. no shared directory),
@@ -153,11 +158,13 @@
server file to the remote host (with possible changes to IP
address and/or port if that applies).
+Note that the usual security risks of using the server over
+remote TCP, arising from the fact that client-server
+communications are unencrypted, still apply.
+
The key must consist of 64 ASCII printable characters except for
-space (this means characters from ! to ~; or from code 33 to 126).
-
-You can use \\[server-generate-key] to get a random authentication
-key."
+space (this means characters from ! to ~; or from code 33 to
+126). You can use \\[server-generate-key] to get a random key."
:group 'server
:type '(choice
(const :tag "Random" nil)
=== modified file 'lisp/startup.el'
--- a/lisp/startup.el 2012-09-19 06:47:01 +0000
+++ b/lisp/startup.el 2012-09-30 09:18:38 +0000
@@ -43,7 +43,10 @@
If the value is nil and `inhibit-startup-screen' is nil, show the
startup screen. If the value is a string, visit the specified file
or directory using `find-file'. If t, open the `*scratch*'
-buffer."
+buffer.
+
+A string value also causes emacsclient to open the specified file
+or directory when no target file is specified."
:type '(choice
(const :tag "Startup screen" nil)
(directory :tag "Directory" :value "~/")
=== modified file 'src/ChangeLog'
--- a/src/ChangeLog 2012-09-30 09:10:59 +0000
+++ b/src/ChangeLog 2012-09-30 09:18:38 +0000
@@ -1,3 +1,7 @@
+2012-09-30 Chong Yidong <address@hidden>
+
+ * fns.c (Frandom): Doc fix.
+
2012-09-30 Martin Rudalics <address@hidden>
* window.c (Vwindow_combination_limit): New default value.
=== modified file 'src/fns.c'
--- a/src/fns.c 2012-09-26 15:19:10 +0000
+++ b/src/fns.c 2012-09-30 09:18:38 +0000
@@ -61,8 +61,9 @@
DEFUN ("random", Frandom, Srandom, 0, 1, 0,
doc: /* Return a pseudo-random number.
-All integers representable in Lisp are equally likely.
- On most systems, this is 29 bits' worth.
+All integers representable in Lisp, i.e. between `most-negative-fixnum'
+and `most-positive-fixnum', inclusive, are equally likely.
+
With positive integer LIMIT, return random number in interval [0,LIMIT).
With argument t, set the random number seed from the current time and pid.
Other values of LIMIT are ignored. */)
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r110277: Update docs for a bunch of 24.3 changes.,
Chong Yidong <=