procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update docs for a bunch of 24.3 changes.

Browse source 
* 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.
This commit is contained in:
Chong Yidong 2012-09-30 17:18:38 +08:00
parent 5938d5196d
commit 48de8b1221
31 changed files with 759 additions and 545 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
doc/emacs/ChangeLog
View file

@ -1,3 +1,29 @@
2012-09-30 Chong Yidong <cyd@gnu.org>
* 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 <rgm@gnu.org>
* cal-xtra.texi (Advanced Calendar/Diary Usage):

29
doc/emacs/ack.texi
View file

@ -644,10 +644,9 @@ statically scoped Emacs lisp.
@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;
@file{cust-print.el}, 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
@file{isearch.el}, 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 @@ providing electric accent keys.
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, C@t{++}, 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, C@t{++},
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.
@item
Christoph Wedler wrote @file{antlr-mode.el}, a major mode for ANTLR
@ -1351,9 +1349,8 @@ Directory Client; and @code{eshell}, a command shell implemented
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.

24
doc/emacs/basic.texi
View file

@ -267,7 +267,8 @@ necessary (@code{scroll-up-command}). @xref{Scrolling}.
Scroll one screen backward, and move point onscreen if necessary
(@code{scroll-down-command}). @xref{Scrolling}.
@item M-x goto-char
@item M-g c
@kindex 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 @@ also specify @var{n} by giving @kbd{M-g M-g} a numeric prefix argument.
@xref{Select Buffer}, for the behavior of @kbd{M-g M-g} when you give it
a plain prefix argument.
@item M-g @key{TAB}
@kindex M-g TAB
@findex 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 @@ narrowed region and the line number relative to the whole buffer.
@kindex M-=
@findex count-words-region
@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 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
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

10
doc/emacs/building.texi
View file

@ -1393,13 +1393,21 @@ putting a line like this in your init file (@pxref{Init File}):
@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.
@vindex 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
@code{help-enable-auto-load} 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

14
doc/emacs/display.texi
View file

@ -1044,9 +1044,9 @@ the left fringe, but no arrow bitmaps, use @code{((top . left)
@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 @@ the location of point is enough to show you that the spaces are
present.
@findex delete-trailing-whitespace
@vindex 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
@code{nil}. 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

1
doc/emacs/emacs.texi
View file

@ -267,6 +267,7 @@ The Minibuffer
* 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

5
doc/emacs/entering.texi
View file

@ -79,11 +79,6 @@ non-@code{nil} value. (In that case, even if you specify one or more
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.
@ignore
@c I do not think this should be mentioned. AFAICS it is just a dodge
@c around inhibit-startup-screen not being settable on a site-wide basis.
or @code{t}, which means to display the @file{*scratch*} buffer.
@end ignore
@node Exiting
@section Exiting Emacs

2
doc/emacs/help.texi
View file

@ -243,7 +243,7 @@ by the innermost Lisp expression in the buffer around point,
(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

9
doc/emacs/killing.texi
View file

@ -709,6 +709,9 @@ rectangle, depending on the command that uses them.
@item C-x r k
Kill the text of the region-rectangle, saving its contents as the
``last killed rectangle'' (@code{kill-rectangle}).
@item 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 @@ yanking a rectangle is so different from yanking linear text that
different yank commands have to be used. Yank-popping is not defined
for rectangles.
@kindex C-x r M-w
@findex copy-rectangle-as-kill
@kbd{C-x r M-w} (@code{copy-rectangle-as-kill}) is the equivalent of
@kbd{M-w} 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}

51
doc/emacs/mini.texi
View file

@ -45,6 +45,7 @@ do not echo.
* 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 @@ password (@pxref{Killing}). You may type either @key{RET} or
@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.
@node Yes or No Prompts
@section 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.
@cindex y or n prompt
For the first type of ``yes or no'' query, the prompt ends with
@samp{(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
@samp{y} 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:
@smallexample
File `foo.el' exists; overwrite? (y or n)
@end smallexample
@noindent
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
@key{next}) scrolls forward; @kbd{C-v} (or @key{PageUp}, or
@key{prior}) 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
@kbd{C-g} dismisses the query, and quits the command that issued it
(@pxref{Quitting}).
@cindex 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:
@smallexample
Buffer foo.el modified; kill anyway? (yes or no)
@end smallexample
@noindent
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.

74
doc/emacs/misc.texi
View file

@ -1509,15 +1509,11 @@ precedence.
@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
@kbd{C-x 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 @@ if the Emacs server is running on a text terminal, the @samp{-c}
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
@code{initial-buffer-choice} is a string (@pxref{Entering Emacs}), the
new frame displays that file or directory instead.
@item -F @var{alist}
@itemx --frame-parameters=@var{alist}
Set the parameters for a newly-created graphical frame
@ -1545,38 +1546,24 @@ evaluate, @emph{not} as a list of files to visit.
@item -f @var{server-file}
@itemx --server-file=@var{server-file}
@cindex @env{EMACS_SERVER_FILE} environment variable
@cindex server file
@vindex server-use-tcp
@vindex 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
@command{emacsclient} 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
@command{emacsclient} to use a specific server file with the @samp{-f}
or @samp{--server-file} option, or by setting the
@env{EMACS_SERVER_FILE} 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.
@vindex server-auth-dir
@cindex 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,
@code{nil}, 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
@file{~/.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 @@ server it finds. (This option is not supported on MS-Windows.)
@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
@kbd{C-x 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.
@xref{Windows 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}

38
doc/emacs/search.texi
View file

@ -17,7 +17,6 @@ thing, but search for patterns instead of fixed strings.
(@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 @@ search.
Some of the characters you type during incremental search have
special effects.
@cindex lax space matching
@kindex M-s SPC @r{(Incremental search)}
@kindex SPC @r{(Incremental search)}
@findex isearch-toggle-lax-whitespace
@vindex 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},
@samp{foo 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
@code{search-whitespace-regexp}. For example, set it to
@samp{"[[: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 @@ Incremental regexp and non-regexp searches have independent defaults.
They also have separate search rings, which you can access with
@kbd{M-p} and @kbd{M-n}.
@vindex 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
@code{search-whitespace-regexp} 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.
@xref{Special 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 @@ instead (@pxref{Mark}). The basic replace commands replace one
is possible to perform several replacements in parallel, using the
command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
@vindex 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
@code{replace-lax-whitespace} 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.

42
doc/lispref/ChangeLog
View file

@ -1,3 +1,45 @@
2012-09-30 Chong Yidong <cyd@gnu.org>
* 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 <cyd@gnu.org>
* os.texi (Startup Summary): Document leim-list.el change.
2012-09-25 Chong Yidong <cyd@gnu.org>
* functions.texi (Defining Functions): defun is now a macro.
2012-09-28 Leo Liu <sdl.web@gmail.com>
* files.texi (Files): Fix typo.

142
doc/lispref/commands.texi
View file

@ -1275,12 +1275,21 @@ describe events by their types; thus, if there is a key binding for
@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.
@cindex mouse position list
This is a @dfn{mouse position list} specifying where the mouse click
occurred; see below for details.
For mouse click events in the text area, mode line, header line, or in
the marginal areas, @var{position} has this form:
@item @var{click-count}
This is the number of rapid repeated presses so far of the same mouse
button. @xref{Repeat Events}.
@end table
To access the contents of a mouse position list in the
@var{position} 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 @@ the marginal areas, @var{position} has this form:
@end example
@noindent
The meanings of these list elements are documented below.
@xref{Accessing 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 @@ happens after the imaginary prefix keys for the event are registered
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 @@ These are the pixel width and height of @var{object} or, if this is
@code{nil}, those of the character glyph clicked on.
@end table
@sp 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 @@ For mouse clicks on a scroll-bar, @var{position} has this form:
@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
@code{0}.
@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},
@code{up}, @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
@code{down} (the down arrow at one end of the scroll bar).
@c The `top', `bottom', and `end-scroll' codes don't seem to be used.
@end table
@item @var{click-count}
This is the number of rapid repeated presses so far of the same mouse
button. @xref{Repeat Events}.
@end table
@node Drag Events
@subsection Drag Events
@ -1429,10 +1439,9 @@ For a drag event, the name of the symbol @var{event-type} contains the
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 @@ represented by lists that look like this:
(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}).
@noindent
@var{position} 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 @@ frame has already been made visible, Emacs has no work to do.
@cindex @code{wheel-up} event
@cindex @code{wheel-down} event
@item (wheel-up @var{position})
@item (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}).
@itemx (wheel-down @var{position})
These kinds of event are generated by moving a mouse wheel. The
@var{position} 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 @@ must be the last element of the list. For example,
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}):
@example
(@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}))
@end 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 @@ event, the value is actually the starting position, which is the only
position such events have.
@end defun
@defun posnp object
This function returns non-@code{nil} if @var{object} is a mouse
oposition list, in either of the formats documented in @ref{Click
Events}); and @code{nil} otherwise.
@end 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.

1
doc/lispref/elisp.texi
View file

@ -516,6 +516,7 @@ Functions
* 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

160
doc/lispref/errors.texi
View file

@ -37,78 +37,69 @@ handled.
@table @code
@item error
@code{"error"}@*
@xref{Errors}.
The message is @samp{error}. @xref{Errors}.
@item quit
@code{"Quit"}@*
@xref{Quitting}.
The message is @samp{Quit}. @xref{Quitting}.
@item args-out-of-range
@code{"Args out of range"}@*
This happens when trying to access an element beyond the range of a
sequence or buffer.@*
@xref{Sequences 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
@xref{Text}.
@item arith-error
@code{"Arithmetic error"}@*
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
@code{"Beginning of buffer"}@*
@xref{Character Motion}.
The message is @samp{Beginning of buffer}. @xref{Character Motion}.
@item buffer-read-only
@code{"Buffer is read-only"}@*
@xref{Read Only Buffers}.
The message is @samp{Buffer is read-only}. @xref{Read Only Buffers}.
@item circular-list
@code{"List contains a loop"}@*
This happens when some operations (e.g. resolving face names)
encounter circular structures.@*
@xref{Circular Objects}.
The message is @samp{List contains a loop}. This happens when a
circular structure is encountered. @xref{Circular Objects}.
@item cl-assertion-failed
@code{"Assertion failed"}@*
This happens when the @code{assert} macro fails a test.@*
@xref{Assertions,,, cl, Common Lisp Extensions}.
The message is @samp{Assertion failed}. This happens when the
@code{assert} macro fails a test. @xref{Assertions,,, cl, Common Lisp
Extensions}.
@item coding-system-error
@code{"Invalid coding system"}@*
@xref{Lisp and Coding Systems}.
The message is @samp{Invalid coding system}. @xref{Lisp and Coding
Systems}.
@item cyclic-function-indirection
@code{"Symbol's chain of function indirections contains a loop"}@*
@xref{Function Indirection}.
The message is @samp{Symbol's chain of function indirections contains
a loop}. @xref{Function Indirection}.
@item cyclic-variable-indirection
@code{"Symbol's chain of variable indirections contains a loop"}@*
@xref{Variable Aliases}.
The message is @samp{Symbol's chain of variable indirections contains
a loop}. @xref{Variable Aliases}.
@item dbus-error
@code{"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}.
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
@code{"End of buffer"}@*
@xref{Character Motion}.
The message is @samp{End of buffer}. @xref{Character Motion}.
@item end-of-file
@code{"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}.
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 @code{file-error}.@*
@xref{Writing 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 file.@*
@xref{Changing 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 @@ because the error message is normally constructed from the data items
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} used.@*
@xref{Files}.
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 file.@*
@xref{How Programs Do Loading}.
problems handling a compressed file. @xref{How Programs Do Loading}.
@c userlock.el
@item file-locked
This is a subcategory of @code{file-error}.@*
@xref{File Locks}.
This is a subcategory of @code{file-error}. @xref{File Locks}.
@c userlock.el
@item file-supersession
This is a subcategory of @code{file-error}.@*
@xref{Modification 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 ftp.@*
@xref{Remote 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
@code{"Invalid function"}@*
@xref{Function Indirection}.
The message is @samp{Invalid function}. @xref{Function Indirection}.
@item invalid-read-syntax
@code{"Invalid read syntax"}@*
@xref{Printed Representation}.
The message is @samp{Invalid read syntax}. @xref{Printed
Representation}.
@item invalid-regexp
@code{"Invalid regexp"}@*
@xref{Regular Expressions}.
The message is @samp{Invalid regexp}. @xref{Regular Expressions}.
@c simple.el
@item mark-inactive
@code{"The mark is not active now"}@*
@xref{The Mark}.
The message is @samp{The mark is not active now}. @xref{The Mark}.
@item no-catch
@code{"No catch for tag"}@*
@xref{Catch 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
@code{"Attempt to modify a protected field"}
The message is @samp{Attempt to modify a protected fiel.
@end ignore
@item scan-error
@code{"Scan error"}@*
This happens when certain syntax-parsing functions
find invalid syntax or mismatched parentheses.@*
@xref{List 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
@code{"Search failed"}@*
@xref{Searching and Matching}.
The message is @samp{Search failed}. @xref{Searching and Matching}.
@item setting-constant
@code{"Attempt to set a constant symbol"}@*
The values of the symbols @code{nil} and @code{t},
and any symbols that start with @samp{:},
may not be changed.@*
@xref{Constant 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
@code{"Text is read-only"}@*
This is a subcategory of @code{buffer-read-only}.@*
@xref{Special Properties}.
The message is @samp{Text is read-only}. This is a subcategory of
@code{buffer-read-only}. @xref{Special Properties}.
@item undefined-color
@code{"Undefined color"}@*
@xref{Color Names}.
The message is @samp{Undefined color}. @xref{Color Names}.
@item void-function
@code{"Symbol's function definition is void"}@*
The message is @samp{Symbol's function definition is void}.
@xref{Function Cells}.
@item void-variable
@code{"Symbol's value as variable is void"}@*
The message is @samp{Symbol's value as variable is void}.
@xref{Accessing Variables}.
@item wrong-number-of-arguments
@code{"Wrong number of arguments"}@*
@xref{Classifying Lists}.
The message is @samp{Wrong number of arguments}. @xref{Classifying
Lists}.
@item wrong-type-argument
@code{"Wrong type argument"}@*
@xref{Type Predicates}.
The message is @samp{Wrong type argument}. @xref{Type Predicates}.
@end table
@ignore 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
@code{"Arithmetic domain error"}
The message is @samp{Arithmetic domain error}.
@item overflow-error
@code{"Arithmetic overflow error"}@*
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
@code{"Arithmetic range error"}
The message is @code{Arithmetic range error}.
@item singularity-error
@code{"Arithmetic singularity error"}@*
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
@code{"Arithmetic underflow error"}@*
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
@end ignore

24
doc/lispref/frames.texi
View file

@ -1529,24 +1529,14 @@ track of such changes. @xref{Misc Events}.
@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.
@c @cindex raising a frame redundant with raise-frame
@cindex 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).

109
doc/lispref/functions.texi
View file

@ -23,6 +23,7 @@ define them.
* 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 @@ Scheme.)
is called @dfn{defining a function}, and it is done with the
@code{defun} special form.
@defspec defun name argument-list body-forms...
@defmac 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 @@ without any hesitation or notification. Emacs does not prevent you
from doing this, because redefining a function is sometimes done
deliberately, and there is no way to distinguish deliberate
redefinition from unintentional redefinition.
@end defspec
@end defmac
@cindex function aliases
@defun defalias name definition &optional docstring
@ -1132,29 +1133,46 @@ examining or altering the structure of closure objects.
@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
@code{(declare (obsolete @dots{}))} form in the function's
@code{defun} 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
@code{make-obsolete}; 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
@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the
warning message says to use @var{current-name} 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. If @var{current-name} is a string, it is the warning
message.
This function marks @var{obsolete-name} as obsolete.
@var{obsolete-name} 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
@var{current-name} 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
@code{nil}, 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 @@ body uses the arguments, as you do for macros.
After an inline function is defined, its inline expansion can be
performed later on in the same file, just like macros.
@node Declare Form
@section The @code{declare} Form
@findex 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.
@anchor{Definition of declare}
@defmac declare @var{specs}@dots{}
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
@emph{very 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}
@var{args}@dots{})}, which should not be quoted. These have the
following effects:
@table @code
@item (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.
@item (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}.
@item (doc-string @var{n})
Use element number @var{n}, if any, as the documentation string.
@item (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.
@xref{Indenting Macros}.
@item (obsolete @var{current-name} @var{when})
Mark the function or macro as obsolete, similar to a call to
@code{make-obsolete} (@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.
@end table
@end defmac
@node Declaring Functions
@section Telling the Compiler that a Function is Defined
@cindex function declaration

16
doc/lispref/help.texi
View file

@ -58,11 +58,17 @@ use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
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

8
doc/lispref/loading.texi
View file

@ -384,11 +384,13 @@ non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
@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

39
doc/lispref/macros.texi
View file

@ -235,43 +235,8 @@ of constants and nonconstant parts. To make this easier, use the
@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.
@defmac declare @var{specs}@dots{}
@anchor{Definition 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:
@table @code
@item (debug @var{edebug-form-spec})
Specify how to step through macro calls for Edebug.
@xref{Instrumenting Macro Calls}.
@item (indent @var{indent-spec})
Specify how to indent calls to this macro. @xref{Indenting Macros},
for more details.
@item (doc-string @var{number})
Specify which element of the macro is the documentation string, if
any.
@end table
A @code{declare} form only has its special effect in the body of a
@code{defmacro} 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}.
@end 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

178
doc/lispref/numbers.texi
View file

@ -48,9 +48,8 @@ to
@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 @@ The value of this variable is the smallest integer that Emacs Lisp can
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 @@ character codepoint.
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
@acronym{IEEE} floating point standard where possible (the standard is
supported by most modern computers).
@acronym{IEEE} 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 @@ compare them, then you test whether two values are the same
@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 @@ If @var{number} is already a floating point number, @code{float} returns
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
@var{number} 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 non-@code{nil}, 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 @@ depending on your machine.
@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 @@ quotient. If there are additional arguments @var{divisors}, then it
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
@code{/} 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.
@cindex @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
@group
(/ 5 2)
@result{} 2
@end group
@group
(/ 5.0 2)
@result{} 2.5
@end group
@group
(/ 5 2.0)
@result{} 2.5
@end group
@group
(/ 5.0 2.0)
@result{} 2.5
@end group
@group
(/ 25 3 2)
@result{} 4
@end group
@group
(/ -17 6)
@result{} -2 @r{(could in theory be @minus{}3 on some machines)}
@result{} -2
@end group
@end example
@cindex @code{arith-error} in division
If you divide an integer by the integer 0, Emacs signals an
@code{arith-error} 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,22 +668,6 @@ otherwise, it signals an @code{arith-error} error.
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.
@example
(% 9 4)
@result{} 1
(% -9 4)
@result{} -1
(% 9 -4)
@result{} 1
(% -9 -4)
@result{} -1
@end example
For any two integers @var{dividend} and @var{divisor},
@example
@ -687,7 +678,19 @@ For any two integers @var{dividend} and @var{divisor},
@end example
@noindent
always equals @var{dividend}.
always equals @var{dividend}. If @var{divisor} is zero, Emacs signals
an @code{arith-error} error.
@example
(% 9 4)
@result{} 1
(% -9 4)
@result{} -1
(% 9 -4)
@result{} 1
(% -9 -4)
@result{} -1
@end example
@end defun
@defun mod dividend divisor
@ -697,10 +700,9 @@ in other words, the remainder after division of @var{dividend}
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 @@ numbers as arguments.
@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 @@ This function returns the logarithm of @var{arg}, with base
returns a NaN.
@end defun
@ignore
@defun 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.
@end defun
@defun 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.
@end defun
@end 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 @@ The mathematical constant @math{pi} (3.14159@dots{}).
@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.
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.
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
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 @@ This function returns a pseudo-random integer. Repeated calls return a
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
@code{most-negative-fixnum} 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.

118
doc/lispref/os.texi
View file

@ -70,13 +70,11 @@ in their turn. The files @file{subdirs.el} are normally generated
automatically when Emacs is installed.
@item
It registers input methods by loading any @file{leim-list.el} file
found in the @code{load-path}.
@c It removes PWD from the environment if it is not accurate.
@c It abbreviates default-directory.
@c 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
@file{leim-list.el} should not exist in those directories).
@vindex before-init-time
@item
@ -1159,6 +1157,20 @@ This function returns the effective @acronym{UID} of the user.
The value may be a floating point number.
@end defun
@defun 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}.
@end defun
@cindex user groups
@defun 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}.
@end defun
@node Time of Day
@section Time of Day
@ -1812,43 +1824,6 @@ minutes, and even if there have been garbage collections and autosaves.
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.
@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}
@var{sec-low} @var{microsec} @var{picosec})}, using the same format as
@code{current-time} (@pxref{Time of Day}).
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:
@smallexample
(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}}
;; @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))
...@var{do the work for a while}...
(when @var{taking-a-break}
(setq 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))))
@end smallexample
@end defun
Do not write an idle timer function containing a loop which does a
certain amount of processing each time around, and exits when
@code{(input-pending-p)} is non-@code{nil}. This approach seems very
@ -1864,16 +1839,50 @@ It blocks out any idle timers that ought to run during that time.
@end itemize
@noindent
For similar reasons, do not write an idle timer function that sets
up another idle time (including the same idle timer) with the
@var{secs} 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.
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.
@noindent
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.
@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}
@var{sec-low} @var{microsec} @var{picosec})}, using the same format as
@code{current-time} (@pxref{Time of Day}).
When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
This is a convenient way to test whether Emacs is idle.
@end 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:
@example
(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{my-resume-timer}.}
(when my-resume-timer
(cancel-timer my-resume-timer))
...@var{do the work for a while}...
(when @var{taking-a-break}
(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
'my-timer-function))))
@end example
@node Terminal Input
@section Terminal Input
@ -1907,7 +1916,6 @@ If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
has no effect except in @sc{cbreak} mode.
@c 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 @@ it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
Emacs uses all 8 bits of input unchanged. This is good for terminals
that use 8-bit character sets.
@c Emacs 19 feature
If @var{quit-char} is non-@code{nil}, it specifies the character to
use for quitting. Normally this character is @kbd{C-g}.
@xref{Quitting}.
@ -1925,7 +1932,6 @@ use for quitting. Normally this character is @kbd{C-g}.
The @code{current-input-mode} function returns the input mode settings
Emacs is currently using.
@c 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},

41
doc/lispref/strings.texi
View file

@ -35,28 +35,31 @@ keyboard character events.
@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.
@xref{Character 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
@code{length} 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
@code{aref} 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 non-@acronym{ASCII} 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 non-@acronym{ASCII}
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 @@ for information about the syntax of characters and strings.
representations and to encode and decode character codes.
@node Predicates for Strings
@section The Predicates for Strings
@section Predicates for Strings
For more information about general sequence and array predicates,
see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.

95
etc/NEWS
View file

@ -76,6 +76,7 @@ You can explicitly require a specific version by passing
* 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 @@ been adding them there, put them somewhere else, eg site-lisp.
** 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 @@ invokes `set-buffer-file-coding-system'.
** 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 @@ treated as images.
: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 @@ On encountering a fatal error, Emacs now outputs a textual description
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,14 +191,33 @@ The PCL-CVS commands are still available via the keyboard.
* 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.
** 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.
*** Global `M-s _' starts a symbol (identifier) incremental search,
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'.
@ -202,29 +227,11 @@ interactively with no prefix arg. Previously, it moved to column 1.
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.
*** Global `M-s _' starts a symbol (identifier) incremental search,
and `M-s _' in Isearch toggles symbol search mode.
`M-s c' in Isearch toggles search case-sensitivity.
** Register changes
+++
*** `C-x r +' is now overloaded to invoke `append-to-register.
@ -233,8 +240,10 @@ and `M-s _' in Isearch toggles symbol search mode.
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 @@ just removing them, as done by `yank-excluded-properties'.
* 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 @@ enabled.
** 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 @@ inefficiency, and not namespace-clean.
* 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 @@ and are now undefined. For backwards compatibility, defun and
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 @@ in Emacs 24.1:
**** `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 @@ result in a warning describing the cycle.
*** `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.

7
lisp/ChangeLog
View file

@ -34,6 +34,13 @@
2012-09-30 Chong Yidong <cyd@gnu.org>
* 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.

2
lisp/minibuffer.el
View file

@ -2332,7 +2332,7 @@ and `read-file-name-function'."
(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

25
lisp/server.el
View file

@ -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 @@ directory residing in a NTFS partition instead."
(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 @@ so you can set the key with this variable and then copy the
server file to the remote host (with possible changes to IP
address and/or port if that applies).
The key must consist of 64 ASCII printable characters except for
space (this means characters from ! to ~; or from code 33 to 126).
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.
You can use \\[server-generate-key] to get a random authentication
key."
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 key."
:group 'server
:type '(choice
(const :tag "Random" nil)

5
lisp/startup.el
View file

@ -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 "~/")

4
src/ChangeLog
View file

@ -1,3 +1,7 @@
2012-09-30 Chong Yidong <cyd@gnu.org>
* fns.c (Frandom): Doc fix.
2012-09-30 Martin Rudalics <rudalics@gmx.at>
* window.c (Vwindow_combination_limit): New default value.

5
src/fns.c
View file

@ -61,8 +61,9 @@ DEFUN ("identity", Fidentity, Sidentity, 1, 1, 0,
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. */)