diff options
31 files changed, 754 insertions, 540 deletions
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index e0ed850c394..c1894fb900b 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -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): diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index 487e3c19c16..8d1e4221a6c 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -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. diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index 16ccdba0866..42bd2a4fde2 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -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 diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 21948f181fb..eaee16ac8d5 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -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 diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 2238570eaa9..2313d117a90 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -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 diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index c18123d7b29..a2eaaf673e5 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -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 diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi index de143516ce8..224ab356d08 100644 --- a/doc/emacs/entering.texi +++ b/doc/emacs/entering.texi @@ -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 diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index d09885c5edd..050ecd150ab 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -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 diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index 1eb53d0d2ec..5510816b067 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -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} diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index 2856db7a4fa..5d2fc804498 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -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. diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 5d7a51a01f5..4f0a1009e30 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -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. - -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}. +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, @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} diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index d5c9783b772..21db02c8ab8 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -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. diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 76f06edaacb..b5c847b4b72 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -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. diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index dc0fa4c639d..93dba237013 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -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. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index db770616820..d46cb071bf7 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -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 diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index a822a2d9608..b7b26c8708c 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -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 diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 356a891fbcd..af6f4b4c079 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -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). diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 9e1d3f9c6ae..cab6d12a3d8 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -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 diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 5dd8f3c11f5..1375a057a5a 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -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 diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 3c9bee96639..aa243185359 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -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 diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index efe298bf647..0a5152a43a1 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -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 diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 7c9672a38c0..a086f2b3af1 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -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. - - Sometimes it is useful to compare numbers with @code{equal}; it +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}, 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,10 +668,18 @@ 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. +For any two integers @var{dividend} and @var{divisor}, + +@example +@group +(+ (% @var{dividend} @var{divisor}) + (* (/ @var{dividend} @var{divisor}) @var{divisor})) +@end group +@end example -An @code{arith-error} results if @var{divisor} is 0. +@noindent +always equals @var{dividend}. If @var{divisor} is zero, Emacs signals +an @code{arith-error} error. @example (% 9 4) @@ -676,18 +691,6 @@ An @code{arith-error} results if @var{divisor} is 0. (% -9 -4) @result{} -1 @end example - -For any two integers @var{dividend} and @var{divisor}, - -@example -@group -(+ (% @var{dividend} @var{divisor}) - (* (/ @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}. @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. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 68e53c78972..54754f8e5e9 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -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,6 +1824,29 @@ 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. + 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 +natural but has two problems: + +@itemize +@item +It blocks out all process output (since Emacs accepts process output +only while waiting). + +@item +It blocks out any idle timers that ought to run during that time. +@end itemize + +@noindent +Similarly, do not write an idle timer function that sets up another +idle timer (including the same idle timer) with @var{secs} argument +less than or equal to the current idleness time. Such a timer will +run almost immediately, and continue running again and again, instead +of waiting for the next time Emacs becomes idle. The correct approach +is to reschedule with an appropriate increment of the current value of +the idleness time, as described below. + @defun current-idle-time If Emacs is idle, this function returns the length of time Emacs has been idle, as a list of four integers: @code{(@var{sec-high} @@ -1820,60 +1855,34 @@ been idle, as a list of four integers: @code{(@var{sec-high} 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 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: + 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: -@smallexample -(defvar resume-timer nil - "Timer that `timer-function' used to reschedule itself, or nil.") +@example +(defvar my-resume-timer nil + "Timer for `my-timer-function' to reschedule itself, or nil.") -(defun timer-function () - ;; @r{If the user types a command while @code{resume-timer}} +(defun my-timer-function () + ;; @r{If the user types a command while @code{my-resume-timer}} ;; @r{is active, the next time this function is called from} - ;; @r{its main idle timer, deactivate @code{resume-timer}.} - (when resume-timer - (cancel-timer resume-timer)) + ;; @r{its main idle timer, deactivate @code{my-resume-timer}.} + (when my-resume-timer + (cancel-timer my-resume-timer)) ...@var{do the work for a while}... (when @var{taking-a-break} - (setq resume-timer + (setq my-resume-timer (run-with-idle-timer ;; Compute an idle time @var{break-length} ;; more than the current value. (time-add (current-idle-time) (seconds-to-time @var{break-length})) nil - 'timer-function)))) -@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 -natural but has two problems: - -@itemize -@item -It blocks out all process output (since Emacs accepts process output -only while waiting). - -@item -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. - -@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. + '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}, diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index b7097e057c0..865435c91b3 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -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. - - 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 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. + + 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. - - 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. +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. +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}. @@ -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,38 +191,25 @@ 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. -+++ -** `C-x 8 RET' is now bound to `insert-char', which is now a command. -`ucs-insert' is now an obsolete alias for `insert-char'. - ---- -** The `z' key no longer has a binding in most special modes. -It used to be bound to `kill-this-buffer', but `z' is too easy to -accidentally type. - -** New option `delete-trailing-lines' specifies whether -M-x delete-trailing-whitespace should delete trailing lines at the end -of the buffer. It defaults to t. - ** Search and Replace changes - ++++ *** Non-regexp Isearch now performs "lax" space matching. Each sequence of spaces in the supplied search string may match any sequence of one or more whitespace characters, as specified by the variable `search-whitespace-regexp'. (This variable is also used by a similar existing feature for regexp Isearch). - ++++ *** New Isearch command `M-s SPC' toggles lax space matching. This applies to both ordinary and regexp Isearch. - ++++ *** New option `replace-lax-whitespace'. If non-nil, `query-replace' uses flexible whitespace matching too. The default is nil. @@ -225,6 +218,20 @@ The default is nil. and `M-s _' in Isearch toggles symbol search mode. `M-s c' in Isearch toggles search case-sensitivity. ++++ +** `C-x 8 RET' is now bound to `insert-char', which is now a command. +`ucs-insert' is now an obsolete alias for `insert-char'. + +--- +** The `z' key no longer has a binding in most special modes. +It used to be bound to `kill-this-buffer', but `z' is too easy to +accidentally type. + ++++ +** New option `delete-trailing-lines' specifies whether +M-x delete-trailing-whitespace should delete trailing lines at the end +of the buffer. It defaults to t. + ** Register changes +++ *** `C-x r +' is now overloaded to invoke `append-to-register. @@ -233,8 +240,10 @@ 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. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 3e1b93ae3ba..d7b8163ae9e 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -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. diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 27c53744d54..cf990019abc 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -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 diff --git a/lisp/server.el b/lisp/server.el index 4fd55bcf6d1..73c253a87a6 100644 --- a/lisp/server.el +++ b/lisp/server.el @@ -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) diff --git a/lisp/startup.el b/lisp/startup.el index 243c9621752..6658e16683b 100644 --- a/lisp/startup.el +++ b/lisp/startup.el @@ -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 "~/") diff --git a/src/ChangeLog b/src/ChangeLog index 12992f1de0a..122dbd903fe 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -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. diff --git a/src/fns.c b/src/fns.c index b4bb9e83fa8..6d6f019b311 100644 --- a/src/fns.c +++ b/src/fns.c @@ -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. */) |