diff options
| author | Chong Yidong <cyd@gnu.org> | 2012-04-20 16:48:50 +0800 |
|---|---|---|
| committer | Chong Yidong <cyd@gnu.org> | 2012-04-20 16:48:50 +0800 |
| commit | c07a4c0b599e0debfb10acdf02ac6559b998a88a (patch) | |
| tree | f87bca47c21f04b43cca2347a21ed89c57b67958 | |
| parent | 6cf2a23e297b8a57a70c2a1dab5aa28b73461b0b (diff) | |
| parent | 50e5ebca7edcf5299b89ff74499991de01e22046 (diff) | |
| download | emacs-c07a4c0b599e0debfb10acdf02ac6559b998a88a.tar.gz | |
Merge from emacs-24 branch
35 files changed, 1136 insertions, 735 deletions
diff --git a/ChangeLog b/ChangeLog index 95baf9c5294..d2da3d8527b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2012-04-20 Ludovic Courtès <ludo@gnu.org> + + * configure.in: Don't use the -R option (Bug#11251). + +2012-04-20 Teodor Zlatanov <tzz@lifelogs.com> + + * info/dir, Makefile.in (INFO_FILES): Add emacs-gnutls. + 2012-04-18 Paul Eggert <eggert@cs.ucla.edu> configure: new option --enable-gcc-warnings (Bug#11207) diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index adbeeaa296c..ad427397524 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -53,12 +53,17 @@ pt-br Rodrigo Real ru Alex Ott sk Miroslav Vaško +** For a major release, add a "New in Emacs XX" section to faq.texi. + ** Remove temporary +++/--- lines in NEWS. ** Try to reorder NEWS: most important things first, related items together. ** Consider bumping customize-changed-options-previous-release. +** cusver-check from admin.el cam help find new defcustoms missing +:version tags. + * BUGS ** Check for modes which bind M-s that conflicts with a new global binding M-s @@ -206,7 +211,7 @@ loading.texi cyd macros.texi cyd maps.texi rgm markers.texi rgm -minibuf.texi +minibuf.texi rgm modes.texi cyd nonascii.texi cyd numbers.texi cyd @@ -214,7 +219,7 @@ objects.texi cyd os.texi cyd package.texi rgm positions.texi cyd -processes.texi +processes.texi rgm searching.texi rgm sequences.texi cyd streams.texi cyd diff --git a/autogen/configure b/autogen/configure index 08f35898ff4..0d9d1abdaa4 100755 --- a/autogen/configure +++ b/autogen/configure @@ -22866,7 +22866,7 @@ case "$opsys" in ## had not yet been defined and was expanded to null. Hence LD_SWITCH_SYSTEM ## had different values in configure (in ac_link) and src/Makefile.in. ## It seems clearer therefore to put this piece in LD_SWITCH_SYSTEM_TEMACS. - gnu-linux) LD_SWITCH_SYSTEM_TEMACS="\$(LD_SWITCH_X_SITE_AUX)" ;; + gnu*) LD_SWITCH_SYSTEM_TEMACS="\$(LD_SWITCH_X_SITE_AUX_RPATH)" ;; *) LD_SWITCH_SYSTEM_TEMACS= ;; esac diff --git a/configure.in b/configure.in index 21b8c9d2b8f..1554e10145f 100644 --- a/configure.in +++ b/configure.in @@ -3510,7 +3510,7 @@ case "$opsys" in ## had not yet been defined and was expanded to null. Hence LD_SWITCH_SYSTEM ## had different values in configure (in ac_link) and src/Makefile.in. ## It seems clearer therefore to put this piece in LD_SWITCH_SYSTEM_TEMACS. - gnu-linux) LD_SWITCH_SYSTEM_TEMACS="\$(LD_SWITCH_X_SITE_AUX)" ;; + gnu*) LD_SWITCH_SYSTEM_TEMACS="\$(LD_SWITCH_X_SITE_AUX_RPATH)" ;; *) LD_SWITCH_SYSTEM_TEMACS= ;; esac diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index b5a25cb1c51..284a1230a83 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,75 @@ +2012-04-20 Chong Yidong <cyd@gnu.org> + + * processes.texi (Asynchronous Processes): Mention nil argument to + start-process. + +2012-04-20 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (Basic Completion): No need to describe obarrays here. + Don't mention obsolete `nospace' argument of all-completions. + (Minibuffer Completion, Completion Commands, Reading File Names) + (Completion Variables): Copyedits. + (Completion Commands): Mention parent keymaps. + Remove obsolete minibuffer-local-filename-must-match-map. + (High-Level Completion): Remove read-variable's almost + word-for-word duplication of read-command. + * elisp.texi, vol1.texi, vol2.texi, minibuf.texi (Completion): + Update "High-Level Completion" description. + +2012-04-19 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (Minibuffers): + * elisp.texi, vol1.texi, vol2.texi: Fix minibuffer subsection order. + + * minibuf.texi: Standardize metasyntactic variables ("history", etc). + Use Texinfo-recommended form of quote+punctuation. + (Intro to Minibuffers): First minibuffer is #1, not #0. + Mention minibuffer-inactive-mode. + (Text from Minibuffer): Copyedits. + (Minibuffer History, Programmed Completion): Fix @var usage. + (Object from Minibuffer): Remove overly pedantic para. + (Minibuffer History): Copyedits. Add face-name-history. + (Initial Input, Yes-or-No Queries, Multiple Queries) + (Minibuffer Windows, Minibuffer Misc): Copyedits. + (Yes-or-No Queries): Tweak example. + (Minibuffer Commands): Add next-complete-history-element. + (Minibuffer Misc): Mention minibuffer-message-timeout, and + minibuffer-inactive-mode. + +2012-04-18 Glenn Morris <rgm@gnu.org> + + * processes.texi (Serial Ports, Byte Packing, Bindat Spec) + (Bindat Functions): Copyedits. + +2012-04-18 Christopher Schmidt <christopher@ch.ristopher.com> + + * files.texi (Saving Buffers): Document `visit and `visit-save' + values of require-final-newline. + +2012-04-18 Glenn Morris <rgm@gnu.org> + + * processes.texi (Output from Processes, Filter Functions): + Mention waiting-for-user-input-p. + (Sentinels, Query Before Exit, System Processes, Transaction Queues): + (Network Servers, Datagrams, Network Processes, Network Options) + (Network Feature Testing, Serial Ports): Copyedits. + (Network): Add encrypted network overview paragraph. + Cross-reference the Emacs-GnuTLS manual. Use @acronym. + +2012-04-17 Chong Yidong <cyd@gnu.org> + + * help.texi (Keys in Documentation): Mention :advertised-binding. + + * keymaps.texi (Menu Bar): Move most of the :advertised-binding + description to help.texi. + +2012-04-16 Glenn Morris <rgm@gnu.org> + + * processes.texi (Process Information, Input to Processes) + (Signals to Processes, Output from Processes, Process Buffers) + (Filter Functions, Decoding Output): Copyedits. + (Accepting Output): Discourage use of `millisec' argument. + 2012-04-15 Glenn Morris <rgm@gnu.org> * processes.texi (Processes, Subprocess Creation, Shell Arguments): diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 76397556b01..4319d5eddda 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -637,8 +637,8 @@ Minibuffers * Multiple Queries:: Asking a series of similar questions. * Reading a Password:: Reading a password from the terminal. * Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Contents:: How such commands access the minibuffer text. * Minibuffer Windows:: Operating on the special minibuffer windows. +* Minibuffer Contents:: How such commands access the minibuffer text. * Recursive Mini:: Whether recursive entry to minibuffer is allowed. * Minibuffer Misc:: Various customization hooks and variables. @@ -648,7 +648,7 @@ Completion * Minibuffer Completion:: Invoking the minibuffer with completion. * Completion Commands:: Minibuffer commands that do completion. * High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.). + (reading buffer names, variable names, etc.). * Reading File Names:: Using completion to read file names and shell commands. * Completion Variables:: Variables controlling completion behavior. diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index ca4504ca967..3597d9f80c4 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -489,11 +489,13 @@ in particular buffers. @defopt require-final-newline This variable determines whether files may be written out that do @emph{not} end with a newline. If the value of the variable is -@code{t}, then @code{save-buffer} silently adds a newline at the end of -the file whenever the buffer being saved does not already end in one. -If the value of the variable is non-@code{nil}, but not @code{t}, then -@code{save-buffer} asks the user whether to add a newline each time the -case arises. +@code{t}, then @code{save-buffer} silently adds a newline at the end +of the buffer whenever it does not already end in one. If the value +is @code{visit}, Emacs adds a missing newline just after it visits the +file. If the value is @code{visit-save}, Emacs adds a missing newline +both on visiting and on saving. For any other non-@code{nil} value, +@code{save-buffer} asks the user whether to add a newline each time +the case arises. If the value of the variable is @code{nil}, then @code{save-buffer} doesn't add newlines at all. @code{nil} is the default value, but a few diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 769b4292d30..5dfb2b05ff8 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -347,6 +347,21 @@ This function scans @var{string} for the above special sequences and replaces them by what they stand for, returning the result as a string. This permits display of documentation that refers accurately to the user's own customized key bindings. + +@cindex advertised binding +If a command has multiple bindings, this function normally uses the +first one it finds. You can specify one particular key binding by +assigning an @code{:advertised-binding} symbol property to the +command, like this: + +@smallexample +(put 'undo :advertised-binding [?\C-/]) +@end smallexample + +@noindent +The @code{:advertised-binding} property also affects the binding shown +in menu items (@pxref{Menu Bar}). The property is ignored if it +specifies a key binding that the command does not actually have. @end defun Here are examples of the special sequences: diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index f8befb8fd90..b12752fdeea 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -2548,17 +2548,8 @@ the same command (if such a key binding exists). This serves as a convenient hint for users who do not know the key binding. If a command has multiple bindings, Emacs normally displays the first one it finds. You can specify one particular key binding by assigning an -@code{:advertised-binding} symbol property to the command. For -instance, the following tells Emacs to show @kbd{C-/} for the -@code{undo} menu item: - -@smallexample -(put 'undo :advertised-binding [?\C-/]) -@end smallexample - -@noindent -If the @code{:advertised-binding} property specifies a key binding -that the command does not actually have, it is ignored. +@code{:advertised-binding} symbol property to the command. @xref{Keys +in Documentation}. @node Tool Bar @subsection Tool bars diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 1be21f5d974..c840eb6ded0 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -29,8 +29,8 @@ argument. * Multiple Queries:: Asking a series of similar questions. * Reading a Password:: Reading a password from the terminal. * Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Contents:: How such commands access the minibuffer text. * Minibuffer Windows:: Operating on the special minibuffer windows. +* Minibuffer Contents:: How such commands access the minibuffer text. * Recursive Mini:: Whether recursive entry to minibuffer is allowed. * Minibuffer Misc:: Various customization hooks and variables. @end menu @@ -59,8 +59,10 @@ boundary between the prompt and the actual text. The minibuffer's window is normally a single line; it grows automatically if the contents require more space. You can explicitly +@c FIXME? Works in 23.4, not 24.0.95. (Bug#11276) resize it temporarily with the window sizing commands; it reverts to its normal size when the minibuffer is exited. You can resize it +@c FIXME? Doesn't work in any version of Emacs? permanently by using the window sizing commands in the frame's other window, when the minibuffer is not active. If the frame contains just a minibuffer, you can change the minibuffer's size by changing the @@ -72,9 +74,9 @@ of variables such as @code{this-command} and @code{last-command} code that uses the minibuffer, if you do not want that to change them. Under some circumstances, a command can use a minibuffer even if -there is an active minibuffer; such minibuffers are called a +there is an active minibuffer; such a minibuffer is called a @dfn{recursive minibuffer}. The first minibuffer is named -@w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by +@w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by incrementing the number at the end of the name. (The names begin with a space so that they won't show up in normal buffer lists.) Of several recursive minibuffers, the innermost (or most recently @@ -90,6 +92,12 @@ to be done. @xref{Text from Minibuffer}, for the non-completion minibuffer local maps. @xref{Completion Commands}, for the minibuffer local maps for completion. +@cindex inactive minibuffer + When a minibuffer is inactive, its major mode is +@code{minibuffer-inactive-mode}, with keymap +@code{minibuffer-inactive-mode-map}. This is only really useful if +the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. + When Emacs is running in batch mode, any request to read from the minibuffer actually reads a line from the standard input descriptor that was supplied when Emacs was started. @@ -110,7 +118,7 @@ middle of a Lisp function. Instead, do all minibuffer input as part of reading the arguments for a command, in the @code{interactive} specification. @xref{Defining Commands}. -@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method +@defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method This function is the most general way to get input from the minibuffer. By default, it accepts arbitrary text and returns it as a string; however, if @var{read} is non-@code{nil}, then it uses @@ -118,8 +126,8 @@ string; however, if @var{read} is non-@code{nil}, then it uses Functions}). The first thing this function does is to activate a minibuffer and -display it with @var{prompt-string} as the prompt. This value must be a -string. Then the user can edit text in the minibuffer. +display it with @var{prompt} (which must be a string) as the +prompt. Then the user can edit text in the minibuffer. When the user types a command to exit the minibuffer, @code{read-from-minibuffer} constructs the return value from the text in @@ -131,7 +139,7 @@ reads the text and returns the resulting Lisp object, unevaluated. The argument @var{default} specifies default values to make available through the history commands. It should be a string, a list of strings, or @code{nil}. The string or strings become the minibuffer's -``future history,'' available to the user with @kbd{M-n}. +``future history'', available to the user with @kbd{M-n}. If @var{read} is non-@code{nil}, then @var{default} is also used as the input to @code{read}, if the user enters empty input. @@ -148,12 +156,13 @@ value of @code{minibuffer-local-map} is used as the keymap. Specifying a keymap is the most important way to customize the minibuffer for various applications such as completion. -The argument @var{hist} specifies which history list variable to use +The argument @var{history} specifies a history list variable to use for saving the input and for history commands used in the minibuffer. -It defaults to @code{minibuffer-history}. @xref{Minibuffer History}. +It defaults to @code{minibuffer-history}. You can optionally specify +a starting position in the history list as well. @xref{Minibuffer History}. If the variable @code{minibuffer-allow-text-properties} is -non-@code{nil}, then the string which is returned includes whatever text +non-@code{nil}, then the string that is returned includes whatever text properties were present in the minibuffer. Otherwise all the text properties are stripped when the value is returned. @@ -163,9 +172,9 @@ the setting of @code{enable-multibyte-characters} (@pxref{Text Representations}) from whichever buffer was current before entering the minibuffer. -Use of @var{initial-contents} is mostly deprecated; we recommend using +Use of @var{initial} is mostly deprecated; we recommend using a non-@code{nil} value only in conjunction with specifying a cons cell -for @var{hist}. @xref{Initial Input}. +for @var{history}. @xref{Initial Input}. @end defun @defun read-string prompt &optional initial history default inherit-input-method @@ -178,11 +187,11 @@ The optional argument @var{default} is used as in @code{read-from-minibuffer}, except that, if non-@code{nil}, it also specifies a default value to return if the user enters null input. As in @code{read-from-minibuffer} it should be a string, a list of -strings, or @code{nil} which is equivalent to an empty string. When +strings, or @code{nil}, which is equivalent to an empty string. When @var{default} is a string, that string is the default value. When it is a list of strings, the first string is the default value. (All these strings are available to the user in the ``future minibuffer -history.'') +history''.) This function works by calling the @code{read-from-minibuffer} function: @@ -201,16 +210,16 @@ This function works by calling the @end smallexample @end defun -@defun read-regexp prompt &optional default-value +@defun read-regexp prompt &optional default This function reads a regular expression as a string from the minibuffer and returns it. The argument @var{prompt} is used as in @code{read-from-minibuffer}. The keymap used is @code{minibuffer-local-map}, and @code{regexp-history} is used as the history list (@pxref{Minibuffer History, regexp-history}). -The optional argument @var{default-value} specifies a default value to +The optional argument @var{default} specifies a default value to return if the user enters null input; it should be a string, or -@code{nil} which is equivalent to an empty string. +@code{nil}, which is equivalent to an empty string. In addition, @code{read-regexp} collects a few useful candidates for input and passes them to @code{read-from-minibuffer}, to make them @@ -234,9 +243,9 @@ function, after computing the list of defaults as described above. @end defun @defvar minibuffer-allow-text-properties -If this variable is @code{nil}, then @code{read-from-minibuffer} strips -all text properties from the minibuffer input before returning it. -This variable also affects @code{read-string}. However, +If this variable is @code{nil}, then @code{read-from-minibuffer} +and @code{read-string} strip all text properties from the minibuffer +input before returning it. However, @code{read-no-blanks-input} (see below), as well as @code{read-minibuffer} and related functions (@pxref{Object from Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all @@ -274,6 +283,12 @@ default, it makes the following bindings: @item @kbd{M-r} @code{previous-matching-history-element} + +@ignore +@c Does not seem worth/appropriate mentioning. +@item @kbd{C-@key{TAB}} +@code{file-cache-minibuffer-complete} +@end ignore @end table @end defvar @@ -304,6 +319,8 @@ This function discards text properties, regardless of the value of @end smallexample @end defun +@c Slightly unfortunate name, suggesting it might be related to the +@c Nextstep port... @defvar minibuffer-local-ns-map This built-in variable is the keymap used as the minibuffer local keymap in the function @code{read-no-blanks-input}. By default, it makes the @@ -388,23 +405,16 @@ This function simply evaluates the result of a call to @end defun @defun edit-and-eval-command prompt form -This function reads a Lisp expression in the minibuffer, and then -evaluates it. The difference between this command and +This function reads a Lisp expression in the minibuffer, evaluates it, +then returns the result. The difference between this command and @code{eval-minibuffer} is that here the initial @var{form} is not optional and it is treated as a Lisp object to be converted to printed representation rather than as a string of text. It is printed with @code{prin1}, so if it is a string, double-quote characters (@samp{"}) appear in the initial text. @xref{Output Functions}. -The first thing @code{edit-and-eval-command} does is to activate the -minibuffer with @var{prompt} as the prompt. Then it inserts the printed -representation of @var{form} in the minibuffer, and lets the user edit it. -When the user exits the minibuffer, the edited text is read with -@code{read} and then evaluated. The resulting value becomes the value -of @code{edit-and-eval-command}. - In the following example, we offer the user an expression with initial -text which is a valid form already: +text that is already a valid form: @smallexample @group @@ -424,7 +434,6 @@ Please edit: (forward-word 1)@point{} @noindent Typing @key{RET} right away would exit the minibuffer and evaluate the expression, thus moving point forward one word. -@code{edit-and-eval-command} returns @code{nil} in this example. @end defun @node Minibuffer History @@ -440,7 +449,7 @@ is a list of strings (previous inputs), most recent first. kinds of inputs. It's the Lisp programmer's job to specify the right history list for each use of the minibuffer. - You specify a minibuffer history list with the optional @var{hist} + You specify a minibuffer history list with the optional @var{history} argument to @code{read-from-minibuffer} or @code{completing-read}. Here are the possible values for it: @@ -456,7 +465,7 @@ Specifying 0 for @var{startpos} is equivalent to just specifying the symbol @var{variable}. @code{previous-history-element} will display the most recent element of the history list in the minibuffer. If you specify a positive @var{startpos}, the minibuffer history functions -behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the +behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the history element currently shown in the minibuffer. For consistency, you should also specify that element of the history @@ -464,7 +473,7 @@ as the initial minibuffer contents, using the @var{initial} argument to the minibuffer input function (@pxref{Initial Input}). @end table - If you don't specify @var{hist}, then the default history list + If you don't specify @var{history}, then the default history list @code{minibuffer-history} is used. For other standard history lists, see below. You can also create your own history list variable; just initialize it to @code{nil} before the first use. @@ -503,15 +512,15 @@ If the value of this variable is @code{nil}, standard functions that read from the minibuffer don't add new elements to the history list. This lets Lisp programs explicitly manage input history by using @code{add-to-history}. By default, @code{history-add-new-input} is -set to a non-@code{nil} value. +non-@code{nil}. @end defvar @defopt history-length The value of this variable specifies the maximum length for all history lists that don't specify their own maximum lengths. If the value is @code{t}, that means there is no maximum (don't delete old -elements). The value of @code{history-length} property of the history -list variable's symbol, if set, overrides this variable for that +elements). If a history list variable's symbol has a non-@code{nil} +@code{history-length} property, it overrides this variable for that particular history list. @end defopt @@ -555,11 +564,19 @@ A history list for arguments that are shell commands. A history list for arguments that are Lisp expressions to evaluate. @end defvar +@defvar face-name-history +A history list for arguments that are faces. +@end defvar + +@c Less common: coding-system-history, input-method-history, +@c command-history, grep-history, grep-find-history, +@c read-envvar-name-history, setenv-history, yes-or-no-p-history. + @node Initial Input @section Initial Input Several of the functions for minibuffer input have an argument called -@var{initial} or @var{initial-contents}. This is a mostly-deprecated +@var{initial}. This is a mostly-deprecated feature for specifying that the minibuffer should start out with certain text, instead of empty as usual. @@ -576,7 +593,7 @@ to offer useful default inputs to the user. There is just one situation where you should specify a string for an @var{initial} argument. This is when you specify a cons cell for the -@var{hist} or @var{history} argument. @xref{Minibuffer History}. +@var{history} argument. @xref{Minibuffer History}. @var{initial} can also be a cons cell of the form @code{(@var{string} . @var{position})}. This means to insert @var{string} in the @@ -588,11 +605,10 @@ inconsistently in different functions. In @code{completing-read}, of 0 means the beginning of the string, 1 means after the first character, etc. In @code{read-minibuffer}, and the other non-completion minibuffer input functions that support this argument, -1 means the beginning of the string 2 means after the first character, +1 means the beginning of the string, 2 means after the first character, etc. -Use of a cons cell as the value for @var{initial} arguments is -deprecated in user code. +Use of a cons cell as the value for @var{initial} arguments is deprecated. @node Completion @section Completion @@ -603,6 +619,7 @@ starting from an abbreviation for it. Completion works by comparing the user's input against a list of valid names and determining how much of the name is determined uniquely by what the user has typed. For example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then +@c "This is the sort of English up with which I will not put." type the first few letters of the name of the buffer to which you wish to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs extends the name as far as it can. @@ -627,7 +644,7 @@ for reading certain kinds of names with completion. * Minibuffer Completion:: Invoking the minibuffer with completion. * Completion Commands:: Minibuffer commands that do completion. * High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.). + (reading buffer names, variable names, etc.). * Reading File Names:: Using completion to read file names and shell commands. * Completion Variables:: Variables controlling completion behavior. @@ -662,20 +679,14 @@ If @var{collection} is an alist (@pxref{Association Lists}), the permissible completions are the elements of the alist that are either strings, or conses whose @sc{car} is a string or symbol. Symbols are converted to strings using @code{symbol-name}. Other -elements of the alist are ignored. (Remember that in Emacs Lisp, the +elements of the alist are ignored. (Remember that in Emacs Lisp, the elements of alists do not @emph{have} to be conses.) In particular, a list of strings is allowed, even though we usually do not think of such lists as alists. @cindex obarray in completion If @var{collection} is an obarray (@pxref{Creating Symbols}), the names -of all symbols in the obarray form the set of permissible completions. The -global variable @code{obarray} holds an obarray containing the names of -all interned Lisp symbols. - -Note that the only valid way to make a new obarray is to create it -empty and then add symbols to it one by one using @code{intern}. -Also, you cannot intern a given symbol in more than one obarray. +of all symbols in the obarray form the set of permissible completions. If @var{collection} is a hash table, then the keys that are strings are the possible completions. Other keys are ignored. @@ -756,16 +767,20 @@ too short). Both of those begin with the string @samp{foobar}. @end smallexample @end defun -@defun all-completions string collection &optional predicate nospace +@c Removed obsolete argument nospace. +@defun all-completions string collection &optional predicate This function returns a list of all possible completions of -@var{string}. The arguments to this function (aside from -@var{nospace}) are the same as those of @code{try-completion}. Also, -this function uses @code{completion-regexp-list} in the same way that +@var{string}. The arguments to this function +@c (aside from @var{nospace}) +are the same as those of @code{try-completion}, and it +uses @code{completion-regexp-list} in the same way that @code{try-completion} does. +@ignore The optional argument @var{nospace} is obsolete. If it is non-@code{nil}, completions that start with a space are ignored unless @var{string} starts with a space. +@end ignore If @var{collection} is a function, it is called with three arguments: @var{string}, @var{predicate} and @code{t}; then @code{all-completions} @@ -835,7 +850,7 @@ pertains to the area after @code{"/usr/"} and before @code{"/doc"}. @end defun If you store a completion alist in a variable, you should mark the -variable as ``risky'' with a non-@code{nil} +variable as ``risky'' by giving it a non-@code{nil} @code{risky-local-variable} property. @xref{File Local Variables}. @defvar completion-ignore-case @@ -864,7 +879,7 @@ proper value is done the first time you do completion using @var{var}. It is done by calling @var{fun} with no arguments. The value @var{fun} returns becomes the permanent value of @var{var}. -Here is a usage example: +Here is an example: @smallexample (defvar foo (lazy-completion-table foo make-my-alist)) @@ -879,7 +894,7 @@ Here is a usage example: This section describes the basic interface for reading from the minibuffer with completion. -@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method +@defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method This function reads a string in the minibuffer, assisting the user by providing completion. It activates the minibuffer with prompt @var{prompt}, which must be a string. @@ -934,13 +949,13 @@ The function @code{completing-read} uses @code{minibuffer-local-must-match-map} if @var{require-match} is non-@code{nil}. @xref{Completion Commands}. -The argument @var{hist} specifies which history list variable to use for +The argument @var{history} specifies which history list variable to use for saving the input and for minibuffer history commands. It defaults to @code{minibuffer-history}. @xref{Minibuffer History}. The argument @var{initial} is mostly deprecated; we recommend using a non-@code{nil} value only in conjunction with specifying a cons cell -for @var{hist}. @xref{Initial Input}. For default input, use +for @var{history}. @xref{Initial Input}. For default input, use @var{default} instead. If the argument @var{inherit-input-method} is non-@code{nil}, then the @@ -949,7 +964,7 @@ Methods}) and the setting of @code{enable-multibyte-characters} (@pxref{Text Representations}) from whichever buffer was current before entering the minibuffer. -If the built-in variable @code{completion-ignore-case} is +If the variable @code{completion-ignore-case} is non-@code{nil}, completion ignores case when comparing the input against the possible matches. @xref{Basic Completion}. In this mode of operation, @var{predicate} must also ignore case, or you will get @@ -1082,8 +1097,8 @@ uses this to highlight text in the completion list for better visual feedback. This is not needed in the minibuffer; for minibuffer completion, you can pass @code{nil}. -This function is called by @code{minibuffer-completion-help}. The -most common way to use it is together with +This function is called by @code{minibuffer-completion-help}. A +common way to use it is together with @code{with-output-to-temp-buffer}, like this: @example @@ -1117,7 +1132,7 @@ keymap makes the following bindings: @end table @noindent -with other characters bound as in @code{minibuffer-local-map} +and uses @code{minibuffer-local-map} as its parent keymap (@pxref{Definition of minibuffer-local-map}). @end defvar @@ -1129,15 +1144,6 @@ minibuffer unconditionally. By default, this keymap makes the following bindings: @table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} - @item @kbd{C-j} @code{minibuffer-complete-and-exit} @@ -1146,25 +1152,21 @@ bindings: @end table @noindent -with other characters bound as in @code{minibuffer-local-map}. +and uses @code{minibuffer-local-completion-map} as its parent keymap. @end defvar @defvar minibuffer-local-filename-completion-map -This is like @code{minibuffer-local-completion-map} -except that it does not bind @key{SPC}. This keymap is used by the -function @code{read-file-name}. +This is a sparse keymap that simply unbinds @key{SPC}; because +filenames can contain spaces. The function @code{read-file-name} +combines this keymap with either @code{minibuffer-local-completion-map} +or @code{minibuffer-local-must-match-map}. @end defvar -@defvar minibuffer-local-filename-must-match-map -This is like @code{minibuffer-local-must-match-map} -except that it does not bind @key{SPC}. This keymap is used by the -function @code{read-file-name}. -@end defvar @node High-Level Completion @subsection High-Level Completion Functions - This section describes the higher-level convenient functions for + This section describes the higher-level convenience functions for reading certain sorts of names with completion. In most cases, you should not call these functions in the middle of a @@ -1238,7 +1240,7 @@ for which @code{commandp} returns @code{t}. @xref{Interactive Call}. The argument @var{default} specifies what to return if the user enters null input. It can be a symbol, a string or a list of strings. If it is a string, @code{read-command} interns it before returning it. -If it is a list, @code{read-command} returns the first element of this list. +If it is a list, @code{read-command} interns the first element of this list. If @var{default} is @code{nil}, that means no default has been specified; then if the user enters null input, the return value is @code{(intern "")}, that is, a symbol whose name is an empty string. @@ -1280,51 +1282,11 @@ complete in the set of extant Lisp symbols, and it uses the @defun read-variable prompt &optional default @anchor{Definition of read-variable} -This function reads the name of a user variable and returns it as a -symbol. - -The argument @var{default} specifies the default value to return if -the user enters null input. It can be a symbol, a string, or a list -of strings. If it is a string, @code{read-variable} interns it to -make the default value. If it is a list, @code{read-variable} interns -the first element. If @var{default} is @code{nil}, that means no -default has been specified; then if the user enters null input, the -return value is @code{(intern "")}. - -@example -@group -(read-variable "Variable name? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Variable name? @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user then types @kbd{fill-p @key{RET}}, @code{read-variable} -returns @code{fill-prefix}. - -In general, @code{read-variable} is similar to @code{read-command}, -but uses the predicate @code{custom-variable-p} instead of -@code{commandp}: - -@cindex @code{custom-variable-p} example -@example -@group -(read-variable @var{prompt}) -@equiv{} -(intern - (completing-read @var{prompt} obarray - 'custom-variable-p t nil)) -@end group -@end example +This function reads the name of a customizable variable and returns it +as a symbol. Its arguments have the same form as those of +@code{read-command}. It behaves just like @code{read-command}, except +that it uses the predicate @code{custom-variable-p} instead of +@code{commandp}. @end defun @deffn Command read-color &optional prompt convert allow-empty display @@ -1342,7 +1304,7 @@ minibuffer. However, when called interactively or if the optional argument @var{convert} is non-@code{nil}, it converts any input color name into the corresponding RGB value string and instead returns that. This function requires a valid color specification to be input. -Empty color names are allowed when @code{allow-empty} is +Empty color names are allowed when @var{allow-empty} is non-@code{nil} and the user enters null input. Interactively, or when @var{display} is non-@code{nil}, the return @@ -1360,7 +1322,7 @@ and @code{read-input-method-name}, in @ref{Input Methods}. The high-level completion functions @code{read-file-name}, @code{read-directory-name}, and @code{read-shell-command} are designed -to read file names, directory names, and shell commands respectively. +to read file names, directory names, and shell commands, respectively. They provide special features, including automatic insertion of the default directory. @@ -1369,15 +1331,29 @@ This function reads a file name, prompting with @var{prompt} and providing completion. As an exception, this function reads a file name using a graphical -file dialog instead of the minibuffer, if (i) it is invoked via a -mouse command, and (ii) the selected frame is on a graphical display -supporting such dialogs, and (iii) the variable @code{use-dialog-box} -is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU -Emacs Manual}), and (iv) the @var{directory} argument, described -below, does not specify a remote file (@pxref{Remote Files,, Remote -Files, emacs, The GNU Emacs Manual}). The exact behavior when using a -graphical file dialog is platform-dependent. Here, we simply document -the behavior when using the minibuffer. +file dialog instead of the minibuffer, if all of the following are +true: + +@enumerate +@item +It is invoked via a mouse command. + +@item +The selected frame is on a graphical display supporting such dialogs. + +@item +The variable @code{use-dialog-box} is non-@code{nil}. +@xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}. + +@item +The @var{directory} argument, described below, does not specify a +remote file. @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}. +@end enumerate + +@noindent +The exact behavior when using a graphical file dialog is +platform-dependent. Here, we simply document the behavior when using +the minibuffer. @code{read-file-name} does not automatically expand the returned file name. You must call @code{expand-file-name} yourself if an absolute @@ -1388,7 +1364,7 @@ The optional argument @var{require-match} has the same meaning as in The argument @var{directory} specifies the directory to use for completing relative file names. It should be an absolute directory -name. If @code{insert-default-directory} is non-@code{nil}, +name. If the variable @code{insert-default-directory} is non-@code{nil}, @var{directory} is also inserted in the minibuffer as initial input. It defaults to the current buffer's value of @code{default-directory}. @@ -1396,9 +1372,9 @@ If you specify @var{initial}, that is an initial file name to insert in the buffer (after @var{directory}, if that is inserted). In this case, point goes at the beginning of @var{initial}. The default for @var{initial} is @code{nil}---don't insert any file name. To see what -@var{initial} does, try the command @kbd{C-x C-v}. @strong{Please -note:} we recommend using @var{default} rather than @var{initial} in -most cases. +@var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting +a file. @strong{Please note:} we recommend using @var{default} rather +than @var{initial} in most cases. If @var{default} is non-@code{nil}, then the function returns @var{default} if the user exits the minibuffer with the same non-empty @@ -1501,7 +1477,7 @@ use the code letters @samp{f} or @samp{F} in their interactive form. @xref{Interactive Codes,, Code Characters for interactive}.) Its value controls whether @code{read-file-name} starts by placing the name of the default directory in the minibuffer, plus the initial file -name if any. If the value of this variable is @code{nil}, then +name, if any. If the value of this variable is @code{nil}, then @code{read-file-name} does not place any initial input in the minibuffer (unless you specify initial input with the @var{initial} argument). In that case, the default directory is still used for @@ -1544,17 +1520,17 @@ The file is @point{} @end example @end defopt -@defun read-shell-command prompt &optional initial-contents hist &rest args +@defun read-shell-command prompt &optional initial history &rest args This function reads a shell command from the minibuffer, prompting with @var{prompt} and providing intelligent completion. It completes the first word of the command using candidates that are appropriate for command names, and the rest of the command words as file names. This function uses @code{minibuffer-local-shell-command-map} as the -keymap for minibuffer input. The @var{hist} argument specifies the +keymap for minibuffer input. The @var{history} argument specifies the history list to use; if is omitted or @code{nil}, it defaults to @code{shell-command-history} (@pxref{Minibuffer History, -shell-command-history}). The optional argument @var{initial-contents} +shell-command-history}). The optional argument @var{initial} specifies the initial content of the minibuffer (@pxref{Initial Input}). The rest of @var{args}, if present, are used as the @var{default} and @var{inherit-input-method} arguments in @@ -1563,20 +1539,22 @@ Input}). The rest of @var{args}, if present, are used as the @defvar minibuffer-local-shell-command-map This keymap is used by @code{read-shell-command} for completing -command and file names that are part of a shell command. +command and file names that are part of a shell command. It uses +@code{minibuffer-local-map} as its parent keymap, and binds @key{TAB} +to @code{completion-at-point}. @end defvar @node Completion Variables @subsection Completion Variables - Here are some variables which can be used to alter the default + Here are some variables that can be used to alter the default completion behavior. @cindex completion styles @defopt completion-styles The value of this variable is a list of completion style (symbols) to use for performing completion. A @dfn{completion style} is a set of -rules for generating completions. Each symbol in occurring this list +rules for generating completions. Each symbol occurring this list must have a corresponding entry in @code{completion-styles-alist}. @end defopt @@ -1623,13 +1601,14 @@ description of the available completion styles. @defopt completion-category-overrides This variable specifies special completion styles and other completion behaviors to use when completing certain types of text. Its value -should be a list of the form @code{(@var{category} . @var{alist})}. -@var{category} is a symbol describing what is being completed; -currently, the @code{buffer} and @code{file} categories are defined, -but others can be defined via specialized completion functions -(@pxref{Programmed Completion}). @var{alist} is an association list -describing how completion should behave for the corresponding -category. The following alist keys are supported: +should be an alist with elements of the form @code{(@var{category} +. @var{alist})}. @var{category} is a symbol describing what is being +completed; currently, the @code{buffer}, @code{file}, and +@code{unicode-name} categories are defined, but others can be defined +via specialized completion functions (@pxref{Programmed Completion}). +@var{alist} is an association list describing how completion should +behave for the corresponding category. The following alist keys are +supported: @table @code @item styles @@ -1662,7 +1641,7 @@ the completion. The value should be a function to run after performing completion. The function should accept two arguments, @var{string} and @var{status}, where @var{string} is the text to which the field was -completed and @var{status} indicates what kind of operation happened: +completed, and @var{status} indicates what kind of operation happened: @code{finished} if text is now complete, @code{sole} if the text cannot be further completed but completion is not finished, or @code{exact} if the text is a valid completion but may be further @@ -1726,9 +1705,10 @@ some completion alternative; @code{nil} otherwise. @item (boundaries . @var{suffix}) This specifies a @code{completion-boundaries} operation. The function -should return @code{(boundaries START . END)}, where START is the -position of the beginning boundary in the specified string, and END is -the position of the end boundary in SUFFIX. +should return @code{(boundaries @var{start} . @var{end})}, where +@var{start} is the position of the beginning boundary in the specified +string, and @var{end} is the position of the end boundary in +@var{suffix}. @item metadata This specifies a request for information about the state of the @@ -1773,7 +1753,7 @@ the same as for @code{display-sort-function}. @defun completion-table-dynamic function This function is a convenient way to write a function that can act as -programmed completion function. The argument @var{function} should be +a programmed completion function. The argument @var{function} should be a function that takes one argument, a string, and returns an alist of possible completions of it. You can think of @code{completion-table-dynamic} as a transducer between that interface @@ -1827,7 +1807,7 @@ satisfy. @item :exclusive If the value is @code{no}, then if the completion table fails to match -the text at point, then @code{completion-at-point} moves on to the +the text at point, @code{completion-at-point} moves on to the next function in @code{completion-at-point-functions} instead of reporting a completion failure. @end table @@ -1841,7 +1821,7 @@ old code to using @code{completion-at-point}. The first function in @code{completion-at-point-functions} to return a non-@code{nil} value is used by @code{completion-at-point}. The remaining functions are not called. The exception to this is when -there is a @code{:exclusive} specification, as described above. +there is an @code{:exclusive} specification, as described above. @end defvar The following function provides a convenient way to perform @@ -1879,7 +1859,7 @@ answer. using the mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either @code{nil} or a list---then it uses a dialog box or pop-up menu to ask the question. Otherwise, it -uses keyboard input. You can force use of the mouse or use of keyboard +uses keyboard input. You can force use either of the mouse or of keyboard input by binding @code{last-nonmenu-event} to a suitable value around the call. @@ -1890,7 +1870,7 @@ the call. This function asks the user a question, expecting input in the echo area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like +and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like @kbd{C-g}, because the question might look like a minibuffer and for that reason the user might try to use @kbd{C-]} to get out. The answer is a single character, with no @key{RET} needed to terminate it. Upper @@ -1914,12 +1894,16 @@ hardwired. The keymap @code{query-replace-map} specifies them. In the following example, the user first types @kbd{q}, which is invalid. At the next prompt the user types @kbd{y}. +@c Need an interactive example, because otherwise the return value +@c obscures the display of the valid answer. @smallexample @group -(y-or-n-p "Do you need a lift? ") +(defun ask () + (interactive) + (y-or-n-p "Do you need a lift? ")) -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears in the echo area:} +;; @r{After evaluation of the preceding definition, @kbd{M-x ask}} +;; @r{causes the following prompt to appear in the echo area:} @end group @group @@ -1951,10 +1935,10 @@ We show successive lines of echo area messages, but only one actually appears on the screen at a time. @end defun -@defun y-or-n-p-with-timeout prompt seconds default-value +@defun y-or-n-p-with-timeout prompt seconds default Like @code{y-or-n-p}, except that if the user fails to answer within @var{seconds} seconds, this function stops waiting and returns -@var{default-value}. It works by setting up a timer; see @ref{Timers}. +@var{default}. It works by setting up a timer; see @ref{Timers}. The argument @var{seconds} may be an integer or a floating point number. @end defun @@ -2022,7 +2006,7 @@ single-character answer in the echo area for each one. The value of @var{list} specifies the objects to ask questions about. It should be either a list of objects or a generator function. If it is a function, it should expect no arguments, and should return either the -next object to ask about, or @code{nil} meaning stop asking questions. +next object to ask about, or @code{nil}, meaning to stop asking questions. The argument @var{prompter} specifies how to ask each question. If @var{prompter} is a string, the question text is computed like this: @@ -2038,8 +2022,8 @@ where @var{object} is the next object to ask about (as obtained from If not a string, @var{prompter} should be a function of one argument (the next object to ask about) and should return the question text. If the value is a string, that is the question to ask the user. The -function can also return @code{t} meaning do act on this object (and -don't ask the user), or @code{nil} meaning ignore this object (and don't +function can also return @code{t}, meaning do act on this object (and +don't ask the user), or @code{nil}, meaning ignore this object (and don't ask the user). The argument @var{actor} says how to act on the answers that the user @@ -2080,7 +2064,7 @@ answer); @var{function} is a function of one argument (an object from When the user responds with @var{char}, @code{map-y-or-n-p} calls @var{function}. If it returns non-@code{nil}, the object is considered -``acted upon,'' and @code{map-y-or-n-p} advances to the next object in +``acted upon'', and @code{map-y-or-n-p} advances to the next object in @var{list}. If it returns @code{nil}, the prompt is repeated for the same object. @@ -2092,12 +2076,14 @@ If @code{map-y-or-n-p} is called in a command that was invoked using the mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either @code{nil} or a list---then it uses a dialog box or pop-up menu to ask the question. In this case, it does not use -keyboard input or the echo area. You can force use of the mouse or use +keyboard input or the echo area. You can force use either of the mouse or of keyboard input by binding @code{last-nonmenu-event} to a suitable value around the call. The return value of @code{map-y-or-n-p} is the number of objects acted on. @end defun +@c FIXME An example of this would be more useful than all the +@c preceding examples of simple things. @node Reading a Password @section Reading a Password @@ -2160,6 +2146,19 @@ This command replaces the minibuffer contents with the value of the regular expression). @end deffn +@deffn Command previous-complete-history-element n +This command replaces the minibuffer contents with the value of the +@var{n}th previous (older) history element that completes the current +contents of the minibuffer before the point. +@end deffn + +@deffn Command next-complete-history-element n +This command replaces the minibuffer contents with the value of the +@var{n}th next (newer) history element that completes the current +contents of the minibuffer before the point. +@end deffn + + @node Minibuffer Windows @section Minibuffer Windows @cindex minibuffer windows @@ -2169,7 +2168,7 @@ and test whether they are active. @defun active-minibuffer-window This function returns the currently active minibuffer window, or -@code{nil} if none is currently active. +@code{nil} if there is none. @end defun @defun minibuffer-window &optional frame @@ -2202,8 +2201,8 @@ there can be more than one minibuffer window if there is more than one frame. @defun minibuffer-window-active-p window -This function returns non-@code{nil} if @var{window}, assumed to be -a minibuffer window, is currently active. +This function returns non-@code{nil} if @var{window} is the currently +active minibuffer window. @end defun @node Minibuffer Contents @@ -2318,7 +2317,7 @@ minibuffer, it scrolls this window. @end defvar @defun minibuffer-selected-window -This function returns the window which was selected when the +This function returns the window that was selected when the minibuffer was entered. If selected window is not a minibuffer window, it returns @code{nil}. @end defun @@ -2329,10 +2328,19 @@ windows. If a float, it specifies a fraction of the height of the frame. If an integer, it specifies a number of lines. @end defopt +@vindex minibuffer-message-timeout @defun minibuffer-message string &rest args This function displays @var{string} temporarily at the end of the -minibuffer text, for two seconds, or until the next input event -arrives, whichever comes first. If @var{args} is non-@code{nil}, the -actual message is obtained by passing @var{string} and @var{args} -through @code{format}. @xref{Formatting Strings}. +minibuffer text, for a few seconds, or until the next input event +arrives, whichever comes first. The variable +@code{minibuffer-message-timeout} specifies the number of seconds to +wait in the absence of input. It defaults to 2. If @var{args} is +non-@code{nil}, the actual message is obtained by passing @var{string} +and @var{args} through @code{format}. @xref{Formatting Strings}. @end defun + +@deffn Command minibuffer-inactive-mode +This is the major mode used in inactive minibuffers. It uses +keymap @code{minibuffer-inactive-mode-map}. This can be useful +if the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. +@end deffn diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 5a08fc9711e..71736584865 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -561,8 +561,13 @@ already exists, then @var{name} is modified (by appending @samp{<1>}, etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to associate with the process. +If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty) +and associates its input and output with @var{buffer-or-name}, without +creating a subprocess. In that case, the remaining arguments +@var{args} are ignored. + The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. +line arguments for the subprocess. In the example below, the first process is started and runs (rather, sleeps) for 100 seconds (the output buffer @samp{foo} is created @@ -728,17 +733,17 @@ happen sooner or later). @section Process Information Several functions return information about processes. -@code{list-processes} is provided for interactive use. -@deffn Command list-processes &optional query-only +@deffn Command list-processes &optional query-only buffer This command displays a listing of all living processes. In addition, it finally deletes any process whose status was @samp{Exited} or @samp{Signaled}. It returns @code{nil}. -The processes are shown in a buffer named @file{*Process List*}, whose -major mode is named Process Menu mode. +The processes are shown in a buffer named @file{*Process List*} +(unless you specify otherwise using the optional argument @var{buffer}), +whose major mode is Process Menu mode. -If @var{query-only} is non-@code{nil} then it lists only processes +If @var{query-only} is non-@code{nil}, it only lists processes whose query flag is non-@code{nil}. @xref{Query Before Exit}. @end deffn @@ -754,8 +759,8 @@ This function returns a list of all processes that have not been deleted. @end defun @defun get-process name -This function returns the process named @var{name}, or @code{nil} if -there is none. An error is signaled if @var{name} is not a string. +This function returns the process named @var{name} (a string), or +@code{nil} if there is none. @smallexample @group @@ -774,7 +779,7 @@ were given to the program. @smallexample @group (process-command (get-process "shell")) - @result{} ("/bin/csh" "-i") + @result{} ("bash" "-i") @end group @end smallexample @end defun @@ -782,11 +787,10 @@ were given to the program. @defun process-contact process &optional key This function returns information about how a network or serial -process was set up. For a network process, when @var{key} is -@code{nil}, it returns @code{(@var{hostname} @var{service})} which -specifies what you connected to. For a serial process, when @var{key} -is @code{nil}, it returns @code{(@var{port} @var{speed})}. For an -ordinary child process, this function always returns @code{t}. +process was set up. When @var{key} is @code{nil}, it returns +@code{(@var{hostname} @var{service})} for a network process, and +@code{(@var{port} @var{speed})} for a serial process. +For an ordinary child process, this function always returns @code{t}. If @var{key} is @code{t}, the value is the complete status information for the connection, server, or serial port; that is, the list of @@ -794,7 +798,8 @@ keywords and values specified in @code{make-network-process} or @code{make-serial-process}, except that some of the values represent the current status instead of what you specified. -For a network process: +For a network process, the values include (see +@code{make-network-process} for a complete list): @table @code @item :buffer @@ -831,7 +836,7 @@ process is started and remains constant as long as the process exists. @end defun @defun process-name process -This function returns the name of @var{process}. +This function returns the name of @var{process}, as a string. @end defun @defun process-status process-name @@ -871,12 +876,6 @@ if @var{process-name} is not the name of an existing process. (process-status (get-buffer "*shell*")) @result{} run @end group -@group -x - @result{} #<process xx<1>> -(process-status x) - @result{} exit -@end group @end smallexample For a network connection, @code{process-status} returns one of the symbols @@ -914,13 +913,9 @@ the remote host is provided as process property @code{remote-tty}. @defun process-coding-system process @anchor{Coding systems for a subprocess} -This function returns a cons cell describing the coding systems in use -for decoding output from @var{process} and for encoding input to -@var{process} (@pxref{Coding Systems}). The value has this form: - -@example -(@var{coding-system-for-decoding} . @var{coding-system-for-encoding}) -@end example +This function returns a cons cell @code{(@var{decode} . @var{encode})}, +describing the coding systems in use for decoding output from, and +encoding input to, @var{process} (@pxref{Coding Systems}). @end defun @defun set-process-coding-system process &optional decoding-system encoding-system @@ -960,6 +955,7 @@ Emacs, which is done with the functions in this section. You must specify the process to send input to, and the input data to send. The data appears on the ``standard input'' of the subprocess. +@c FIXME which? Some operating systems have limited space for buffered input in a @acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} periodically amidst the other characters, to force them through. For @@ -986,26 +982,14 @@ the current buffer's process. @defun process-send-string process string This function sends @var{process} the contents of @var{string} as -standard input. If it is @code{nil}, the current buffer's process is used. - - The function returns @code{nil}. +standard input. It returns @code{nil}. For example, to make a +Shell buffer list files: @smallexample @group (process-send-string "shell<1>" "ls\n") @result{} nil @end group - - -@group ----------- Buffer: *shell* ---------- -... -introduction.texi syntax-tables.texi~ -introduction.texi~ text.texi -introduction.txt text.texi~ -... ----------- Buffer: *shell* ---------- -@end group @end smallexample @end defun @@ -1021,7 +1005,6 @@ is unimportant which number is larger.) @defun process-send-eof &optional process This function makes @var{process} see an end-of-file in its input. The @acronym{EOF} comes after any text already sent to it. - The function returns @var{process}. @smallexample @@ -1052,7 +1035,7 @@ system. For example, the signal @code{SIGINT} means that the user has typed @kbd{C-c}, or that some analogous thing has happened. Each signal has a standard effect on the subprocess. Most signals -kill the subprocess, but some stop or resume execution instead. Most +kill the subprocess, but some stop (or resume) execution instead. Most signals can optionally be handled by programs; if the program handles the signal, then we can say nothing in general about its effects. @@ -1061,7 +1044,7 @@ section. Emacs also sends signals automatically at certain times: killing a buffer sends a @code{SIGHUP} signal to all its associated processes; killing Emacs sends a @code{SIGHUP} signal to all remaining processes. (@code{SIGHUP} is a signal that usually indicates that the -user hung up the phone.) +user ``hung up the phone'', i.e., disconnected.) Each of the signal-sending functions takes two optional arguments: @var{process} and @var{current-group}. @@ -1105,6 +1088,8 @@ and cannot be handled by the subprocess. @defun quit-process &optional process current-group This function sends the signal @code{SIGQUIT} to the process @var{process}. This signal is the one sent by the ``quit +@c FIXME? Never heard of C-b being used for this. In readline, eg +@c bash, that is backward-word. character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside Emacs. @end defun @@ -1129,11 +1114,12 @@ stopped previously. @defun signal-process process signal This function sends a signal to process @var{process}. The argument -@var{signal} specifies which signal to send; it should be an integer. +@var{signal} specifies which signal to send; it should be an integer, +or a symbol whose name is a signal. -The @var{process} argument can be a system process @acronym{ID}; that -allows you to send signals to processes that are not children of -Emacs. @xref{System Processes}. +The @var{process} argument can be a system process @acronym{ID} (an +integer); that allows you to send signals to processes that are not +children of Emacs. @xref{System Processes}. @end defun @node Output from Processes @@ -1143,10 +1129,10 @@ Emacs. @xref{System Processes}. There are two ways to receive the output that a subprocess writes to its standard output stream. The output can be inserted in a buffer, -which is called the associated buffer of the process, or a function -called the @dfn{filter function} can be called to act on the output. If -the process has no buffer and no filter function, its output is -discarded. +which is called the associated buffer of the process (@pxref{Process +Buffers}), or a function called the @dfn{filter function} can be +called to act on the output. If the process has no buffer and no +filter function, its output is discarded. When a subprocess terminates, Emacs reads any pending output, then stops reading output from that subprocess. Therefore, if the @@ -1154,19 +1140,20 @@ subprocess has children that are still live and still producing output, Emacs won't receive that output. Output from a subprocess can arrive only while Emacs is waiting: when -reading terminal input, in @code{sit-for} and @code{sleep-for} -(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting -Output}). This minimizes the problem of timing errors that usually -plague parallel programming. For example, you can safely create a -process and only then specify its buffer or filter function; no output -can arrive before you finish, if the code in between does not call any -primitive that waits. +reading terminal input (see the function @code{waiting-for-user-input-p}), +in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), and in +@code{accept-process-output} (@pxref{Accepting Output}). This +minimizes the problem of timing errors that usually plague parallel +programming. For example, you can safely create a process and only +then specify its buffer or filter function; no output can arrive +before you finish, if the code in between does not call any primitive +that waits. @defvar process-adaptive-read-buffering On some systems, when Emacs reads the output from a subprocess, the output data is read in very small blocks, potentially resulting in very poor performance. This behavior can be remedied to some extent -by setting the variable @var{process-adaptive-read-buffering} to a +by setting the variable @code{process-adaptive-read-buffering} to a non-@code{nil} value (the default), as it will automatically delay reading from such processes, thus allowing them to produce more output before Emacs tries to read it. @@ -1235,9 +1222,9 @@ to insert, and updates it to point after the inserted text. That is why successive batches of output are inserted consecutively. Filter functions normally should use this marker in the same fashion -as is done by direct insertion of output in the buffer. A good -example of a filter function that uses @code{process-mark} is found at -the end of the following section. +as is done by direct insertion of output in the buffer. For an +example of a filter function that uses @code{process-mark}, +@pxref{Process Filter Example}. When the user is expected to enter input in the process buffer for transmission to the process, the process marker separates the new input @@ -1285,14 +1272,16 @@ there is no filter. The filter function can only be called when Emacs is waiting for something, because process output arrives only at such times. Emacs -waits when reading terminal input, in @code{sit-for} and -@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output} -(@pxref{Accepting Output}). +waits when reading terminal input (see the function +@code{waiting-for-user-input-p}), in @code{sit-for} and +@code{sleep-for} (@pxref{Waiting}), and in +@code{accept-process-output} (@pxref{Accepting Output}). A filter function must accept two arguments: the associated process and a string, which is output just received from it. The function is then free to do whatever it chooses with the output. +@c Note this text is duplicated in the sentinels section. Quitting is normally inhibited within a filter function---otherwise, the effect of typing @kbd{C-g} at command level or to quit a user command would be unpredictable. If you want to permit quitting inside @@ -1303,19 +1292,20 @@ cases, the right way to do this is with the macro If an error happens during execution of a filter function, it is caught automatically, so that it doesn't stop the execution of whatever program was running when the filter function was started. However, if -@code{debug-on-error} is non-@code{nil}, the error-catching is turned -off. This makes it possible to use the Lisp debugger to debug the +@code{debug-on-error} is non-@code{nil}, errors are not caught. +This makes it possible to use the Lisp debugger to debug the filter function. @xref{Debugger}. - Many filter functions sometimes or always insert the text in the + Many filter functions sometimes (or always) insert the output in the process's buffer, mimicking the actions of Emacs when there is no -filter. Such filter functions need to use @code{set-buffer} in order to -be sure to insert in that buffer. To avoid setting the current buffer -semipermanently, these filter functions must save and restore the -current buffer. They should also check whether the buffer is still -alive, update the process marker, and in some cases update the value -of point. Here is how to do these things: - +filter. Such filter functions need to make sure that they save the +current buffer, select the correct buffer (if different) before +inserting output, and then restore the original buffer. +They should also check whether the buffer is still alive, update the +process marker, and in some cases update the value of point. Here is +how to do these things: + +@anchor{Process Filter Example} @smallexample @group (defun ordinary-insertion-filter (proc string) @@ -1325,7 +1315,7 @@ of point. Here is how to do these things: @end group @group (save-excursion - ;; @r{Insert the text, advancing the process marker.} + ;; @r{Insert the text, advancing the process marker.} (goto-char (process-mark proc)) (insert string) (set-marker (process-mark proc) (point))) @@ -1333,14 +1323,8 @@ of point. Here is how to do these things: @end group @end smallexample -@noindent -The reason to use @code{with-current-buffer}, rather than using -@code{save-excursion} to save and restore the current buffer, is so as -to preserve the change in point made by the second call to -@code{goto-char}. - To make the filter force the process buffer to be visible whenever new -text arrives, insert the following line just before the +text arrives, you could insert a line like the following just before the @code{with-current-buffer} construct: @smallexample @@ -1351,12 +1335,16 @@ text arrives, insert the following line just before the previously, eliminate the variable @code{moving} and call @code{goto-char} unconditionally. +@ignore In earlier Emacs versions, every filter function that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for filter functions; -they never need to do it explicitly. @xref{Match Data}. +they never need to do it explicitly. +@end ignore + Note that Emacs automatically saves and restores the match data +while executing filter functions. @xref{Match Data}. - The output to the function may come in chunks of any size. A program + The output to the filter may come in chunks of any size. A program that produces the same output twice in a row may send it as one batch of 200 characters one time, and five batches of 40 characters the next. If the filter looks for certain text strings in the subprocess output, make @@ -1374,7 +1362,7 @@ This function returns the filter function of @var{process}, or @code{nil} if it has none. @end defun - Here is an example of use of a filter function: + Here is an example of the use of a filter function: @smallexample @group @@ -1394,7 +1382,7 @@ if it has none. (process-send-string "shell" "ls ~/other\n") @result{} nil kept - @result{} ("lewis@@slug[8] % " + @result{} ("lewis@@slug:$ " @end group @group "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ @@ -1450,8 +1438,8 @@ bytes, Emacs by default uses @code{no-conversion} for it; see @ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to control this behavior. - @strong{Warning:} Coding systems such as @code{undecided} which -determine the coding system from the data do not work entirely + @strong{Warning:} Coding systems such as @code{undecided}, which +determine the coding system from the data, do not work entirely reliably with asynchronous subprocess output. This is because Emacs has to process asynchronous subprocess output in batches, as it arrives. Emacs must try to detect the proper coding system from one @@ -1469,7 +1457,7 @@ output as a multibyte string or as a unibyte string according to the process's filter coding system. Emacs decodes the output according to the process output coding system, which usually produces a multibyte string, except for coding systems -such as @code{binary} and @code{raw-text} +such as @code{binary} and @code{raw-text}. @node Accepting Output @subsection Accepting Output from Processes @@ -1487,7 +1475,6 @@ output is inserted in the associated buffers or given to their filter functions. If @var{process} is non-@code{nil} then this function does not return until some output has been received from @var{process}. -@c Emacs 19 feature The arguments @var{seconds} and @var{millisec} let you specify timeout periods. The former specifies a period measured in seconds and the latter specifies one measured in milliseconds. The two time periods @@ -1495,10 +1482,10 @@ thus specified are added together, and @code{accept-process-output} returns after that much time, whether or not there has been any subprocess output. -The argument @var{millisec} is semi-obsolete nowadays because -@var{seconds} can be a floating point number to specify waiting a -fractional number of seconds. If @var{seconds} is 0, the function -accepts whatever output is pending but does not wait. +The argument @var{millisec} is obsolete (and should not be used), +because @var{seconds} can be a floating point number to specify +waiting a fractional number of seconds. If @var{seconds} is 0, the +function accepts whatever output is pending but does not wait. @c Emacs 22.1 feature If @var{process} is a process, and the argument @var{just-this-one} is @@ -1529,6 +1516,7 @@ describing the type of event. The string describing the event looks like one of the following: +@c FIXME? Also "killed\n" - see example below? @itemize @bullet @item @code{"finished\n"}. @@ -1545,7 +1533,7 @@ describing the type of event. A sentinel runs only while Emacs is waiting (e.g., for terminal input, or for time to elapse, or for process output). This avoids the -timing errors that could result from running them at random places in +timing errors that could result from running sentinels at random places in the middle of other Lisp programs. A program can wait, so that sentinels will run, by calling @code{sit-for} or @code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting @@ -1569,6 +1557,7 @@ should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. If the buffer is dead, @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. +@c Note this text is duplicated in the filter functions section. Quitting is normally inhibited within a sentinel---otherwise, the effect of typing @kbd{C-g} at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a @@ -1579,8 +1568,8 @@ right way to do this is with the macro @code{with-local-quit}. If an error happens during execution of a sentinel, it is caught automatically, so that it doesn't stop the execution of whatever programs was running when the sentinel was started. However, if -@code{debug-on-error} is non-@code{nil}, the error-catching is turned -off. This makes it possible to use the Lisp debugger to debug the +@code{debug-on-error} is non-@code{nil}, errors are not caught. +This makes it possible to use the Lisp debugger to debug the sentinel. @xref{Debugger}. While a sentinel is running, the process sentinel is temporarily @@ -1588,10 +1577,14 @@ set to @code{nil} so that the sentinel won't run recursively. For this reason it is not possible for a sentinel to specify a new sentinel. +@ignore In earlier Emacs versions, every sentinel that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for sentinels; they never need to do -it explicitly. @xref{Match Data}. +it explicitly. +@end ignore + Note that Emacs automatically saves and restores the match data +while executing sentinels. @xref{Match Data}. @defun set-process-sentinel process sentinel This function associates @var{sentinel} with @var{process}. If @@ -1599,7 +1592,7 @@ This function associates @var{sentinel} with @var{process}. If The default behavior when there is no sentinel is to insert a message in the process's buffer when the process status changes. -Changes in process sentinel take effect immediately---if the sentinel +Changes in process sentinels take effect immediately---if the sentinel is slated to be run but has not been called yet, and you specify a new sentinel, the eventual call to the sentinel will use the new one. @@ -1627,7 +1620,7 @@ has none. @defun waiting-for-user-input-p While a sentinel or filter function is running, this function returns non-@code{nil} if Emacs was waiting for keyboard input from the user at -the time the sentinel or filter function was called, @code{nil} if it +the time the sentinel or filter function was called, or @code{nil} if it was not. @end defun @@ -1637,7 +1630,7 @@ was not. When Emacs exits, it terminates all its subprocesses by sending them the @code{SIGHUP} signal. Because subprocesses may be doing valuable work, Emacs normally asks the user to confirm that it is ok -to terminate them. Each process has a query flag which, if +to terminate them. Each process has a query flag, which, if non-@code{nil}, says that Emacs should ask for confirmation before exiting and thus killing that process. The default for the query flag is @code{t}, meaning @emph{do} query. @@ -1656,7 +1649,7 @@ shell process to avoid querying: @smallexample @group (set-process-query-on-exit-flag (get-process "shell") nil) - @result{} t + @result{} nil @end group @end smallexample @end defun @@ -1668,7 +1661,7 @@ shell process to avoid querying: In addition to accessing and manipulating processes that are subprocesses of the current Emacs session, Emacs Lisp programs can also access other processes running on the same machine. We call -these @dfn{system processes}, to distinguish between them and Emacs +these @dfn{system processes}, to distinguish them from Emacs subprocesses. Emacs provides several primitives for accessing system processes. @@ -1688,7 +1681,7 @@ This function returns an alist of attributes for the process specified by its process ID @var{pid}. Each association in the alist is of the form @code{(@var{key} . @var{value})}, where @var{key} designates the attribute and @var{value} is the value of that attribute. The various -attribute @var{key}'s that this function can return are listed below. +attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. Values that are numbers can be either integer or floating-point, @@ -1849,6 +1842,8 @@ as @code{shell-command}. @section Transaction Queues @cindex transaction queue +@c That's not very informative. What is a transaction, and when might +@c I want to use one? You can use a @dfn{transaction queue} to communicate with a subprocess using transactions. First use @code{tq-create} to create a transaction queue communicating with a specified process. Then you can call @@ -1878,8 +1873,11 @@ text at the end of the entire answer, but nothing before; that's how If the argument @var{delay-question} is non-@code{nil}, delay sending this question until the process has finished replying to any previous questions. This produces more reliable results with some processes. +@ignore +@c Let's not mention it then. The return value of @code{tq-enqueue} itself is not meaningful. +@end ignore @end defun @defun tq-close queue @@ -1897,10 +1895,11 @@ Transaction queues are implemented by means of a filter function. @cindex UDP Emacs Lisp programs can open stream (TCP) and datagram (UDP) network -connections to other processes on the same machine or other machines. +connections (@pxref{Datagrams}) to other processes on the same machine +or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object. However, the process you are -communicating with is not a child of the Emacs process, so it has no +communicating with is not a child of the Emacs process, has no process @acronym{ID}, and you can't kill it or send it signals. All you can do is send and receive data. @code{delete-process} closes the connection, but does not kill the program at the other end; that @@ -1928,7 +1927,7 @@ network connection or server, @code{serial} for a serial port connection, or @code{real} for a real subprocess. The @code{process-status} function returns @code{open}, -@code{closed}, @code{connect}, and @code{failed} for network +@code{closed}, @code{connect}, or @code{failed} for network connections. For a network server, the status is always @code{listen}. None of those values is possible for a real subprocess. @xref{Process Information}. @@ -1938,35 +1937,48 @@ subprocess. @xref{Process Information}. process, being stopped means not accepting new connections. (Up to 5 connection requests will be queued for when you resume the server; you can increase this limit, unless it is imposed by the operating -system.) For a network stream connection, being stopped means not -processing input (any arriving input waits until you resume the -connection). For a datagram connection, some number of packets may be -queued but input may be lost. You can use the function +system---see the @code{:server} keyword of @code{make-network-process}, +@ref{Network Processes}.) For a network stream connection, being +stopped means not processing input (any arriving input waits until you +resume the connection). For a datagram connection, some number of +packets may be queued but input may be lost. You can use the function @code{process-command} to determine whether a network connection or server is stopped; a non-@code{nil} value means yes. @cindex network connection, encrypted @cindex encrypted network connections -@cindex TLS network connections -@cindex STARTTLS network connections -@defun open-network-stream name buffer-or-name host service &rest parameters +@cindex @acronym{TLS} network connections +@cindex @acronym{STARTTLS} network connections +Emacs can create encrypted network connections, using either built-in +or external support. The built-in support uses the GnuTLS +(``Transport Layer Security'') library; see +@uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}. +If your Emacs was compiled with GnuTLS support, the function +@code{gnutls-available-p} is defined and returns non-@code{nil}. For +more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}. +The external support uses the @file{starttls.el} library, which +requires a helper utility such as @command{gnutls-cli} to be installed +on the system. The @code{open-network-stream} function can +transparently handle the details of creating encrypted connections for +you, using whatever support is available. + +@defun open-network-stream name buffer host service &rest parameters This function opens a TCP connection, with optional encryption, and returns a process object that represents the connection. The @var{name} argument specifies the name for the process object. It is modified as necessary to make it unique. -The @var{buffer-or-name} argument is the buffer to associate with the +The @var{buffer} argument is the buffer to associate with the connection. Output from the connection is inserted in the buffer, unless you specify a filter function to handle the output. If -@var{buffer-or-name} is @code{nil}, it means that the connection is not +@var{buffer} is @code{nil}, it means that the connection is not associated with any buffer. The arguments @var{host} and @var{service} specify where to connect to; @var{host} is the host name (a string), and @var{service} is the name of a defined network service (a string) or a port number (an integer). -@c FIXME? Is this too lengthy for the printed manual? The remaining arguments @var{parameters} are keyword/argument pairs that are mainly relevant to encrypted connections: @@ -1983,14 +1995,15 @@ The type of connection. Options are: An ordinary, unencrypted connection. @item tls @itemx ssl -A TLS (``Transport Layer Security'') connection. +A @acronym{TLS} (``Transport Layer Security'') connection. @item nil @itemx network Start with a plain connection, and if parameters @samp{:success} and @samp{:capability-command} are supplied, try to upgrade to an encrypted -connection via STARTTLS. If that fails, retain the unencrypted connection. +connection via @acronym{STARTTLS}. If that fails, retain the +unencrypted connection. @item starttls -As for @code{nil}, but if STARTTLS fails drop the connection. +As for @code{nil}, but if @acronym{STARTTLS} fails drop the connection. @item shell A shell connection. @end table @@ -2009,22 +2022,22 @@ command @var{capability-command}. The latter defaults to the former. @item :starttls-function @var{function} Function of one argument (the response to @var{capability-command}), -which returns either @code{nil}, or the command to activate STARTTLS +which returns either @code{nil}, or the command to activate @acronym{STARTTLS} if supported. @item :success @var{regexp} -Regular expression matching a successful STARTTLS negotiation. +Regular expression matching a successful @acronym{STARTTLS} negotiation. @item :use-starttls-if-possible @var{boolean} -If non-@code{nil}, do opportunistic STARTTLS upgrades even if Emacs -doesn't have built-in TLS support. +If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs +doesn't have built-in @acronym{TLS} support. @item :client-certificate @var{list-or-t} Either a list of the form @code{(@var{key-file} @var{cert-file})}, naming the certificate key file and certificate file itself, or @code{t}, meaning to query @code{auth-source} for this information -(@pxref{Top,,auth-source, auth, Emacs auth-source Library}). -Only used for TLS or STARTTLS. +(@pxref{Top,,Overview, auth, The Auth-Source Manual}). +Only used for @acronym{TLS} or @acronym{STARTTLS}. @item :return-list @var{cons-or-nil} The return value of this function. If omitted or @code{nil}, return a @@ -2048,18 +2061,20 @@ The connection type: @samp{plain} or @samp{tls}. @section Network Servers @cindex network servers - You create a server by calling @code{make-network-process} with -@code{:server t}. The server will listen for connection requests from -clients. When it accepts a client connection request, that creates a -new network connection, itself a process object, with the following -parameters: + You create a server by calling @code{make-network-process} +(@pxref{Network Processes}) with @code{:server t}. The server will +listen for connection requests from clients. When it accepts a client +connection request, that creates a new network connection, itself a +process object, with the following parameters: @itemize @bullet @item The connection's process name is constructed by concatenating the server process's @var{name} with a client identification string. The +@c FIXME? What about IPv6? Say briefly what the difference is? client identification string for an IPv4 connection looks like -@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a +@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}, which represents an +address and port number. Otherwise, it is a unique number in brackets, as in @samp{<@var{nnn}>}. The number is unique for each connection in the Emacs session. @@ -2080,7 +2095,7 @@ uses its filter and sentinel; their sole purpose is to initialize connections made to the server. @item -The connection's process contact info is set according to the client's +The connection's process contact information is set according to the client's addressing information (typically an IP address and a port number). This information is associated with the @code{process-contact} keywords @code{:host}, @code{:service}, @code{:remote}. @@ -2097,7 +2112,7 @@ The client process's plist is initialized from the server's plist. @section Datagrams @cindex datagrams - A datagram connection communicates with individual packets rather + A @dfn{datagram} connection communicates with individual packets rather than streams of data. Each call to @code{process-send} sends one datagram packet (@pxref{Input to Processes}), and each datagram received results in one call to the filter function. @@ -2150,7 +2165,8 @@ process object that represents it. The arguments @var{args} are a list of keyword/argument pairs. Omitting a keyword is always equivalent to specifying it with value @code{nil}, except for @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here -are the meaningful keywords: +are the meaningful keywords (those corresponding to network options +are listed in the following section): @table @asis @item :name @var{name} @@ -2166,7 +2182,7 @@ connection. Both connections and servers can be of these types. @item :server @var{server-flag} If @var{server-flag} is non-@code{nil}, create a server. Otherwise, create a connection. For a stream type server, @var{server-flag} may -be an integer which then specifies the length of the queue of pending +be an integer, which then specifies the length of the queue of pending connections to the server. The default queue length is 5. @item :host @var{host} @@ -2177,7 +2193,7 @@ specify a valid address for the local host, and only clients connecting to that address will be accepted. @item :service @var{service} -@var{service} specifies a port number to connect to, or, for a server, +@var{service} specifies a port number to connect to; or, for a server, the port number to listen on. It should be a service name that translates to a port number, or an integer specifying the port number directly. For a server, it can also be @code{t}, which means to let @@ -2188,18 +2204,18 @@ the system select an unused port number. communication. @code{nil} means determine the proper address family automatically for the given @var{host} and @var{service}. @code{local} specifies a Unix socket, in which case @var{host} is -ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6 +ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6, respectively. @item :local @var{local-address} For a server process, @var{local-address} is the address to listen on. -It overrides @var{family}, @var{host} and @var{service}, and you -may as well not specify them. +It overrides @var{family}, @var{host} and @var{service}, so you +might as well not specify them. @item :remote @var{remote-address} For a connection, @var{remote-address} is the address to connect to. -It overrides @var{family}, @var{host} and @var{service}, and you -may as well not specify them. +It overrides @var{family}, @var{host} and @var{service}, so you +might as well not specify them. For a datagram server, @var{remote-address} specifies the initial setting of the remote datagram address. @@ -2223,7 +2239,7 @@ integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f} port number @var{p}. @item -A local address is represented as a string which specifies the address +A local address is represented as a string, which specifies the address in the local address space. @item @@ -2245,8 +2261,8 @@ second argument matching @code{"open"} (if successful) or has succeeded or failed. @item :stop @var{stopped} -Start the network connection or server in the `stopped' state if -@var{stopped} is non-@code{nil}. +If @var{stopped} is non-@code{nil}, start the network connection or +server in the ``stopped'' state. @item :buffer @var{buffer} Use @var{buffer} as the process buffer. @@ -2267,6 +2283,11 @@ Initialize the process query flag to @var{query-flag}. @item :filter @var{filter} Initialize the process filter to @var{filter}. +@item :filter-multibyte @var{multibyte} +If @var{multibyte} is non-@code{nil}, strings given to the process +filter are multibyte, otherwise they are unibyte. The default is the +default value of @code{enable-multibyte-characters}. + @item :sentinel @var{sentinel} Initialize the process sentinel to @var{sentinel}. @@ -2274,7 +2295,7 @@ Initialize the process sentinel to @var{sentinel}. Initialize the log function of a server process to @var{log}. The log function is called each time the server accepts a network connection from a client. The arguments passed to the log function are -@var{server}, @var{connection}, and @var{message}, where @var{server} +@var{server}, @var{connection}, and @var{message}; where @var{server} is the server process, @var{connection} is the new process for the connection, and @var{message} is a string describing what has happened. @@ -2311,7 +2332,7 @@ Using this option may require special privileges on some systems. @item :broadcast @var{broadcast-flag} If @var{broadcast-flag} is non-@code{nil} for a datagram process, the process will receive datagram packet sent to a broadcast address, and -be able to send packets to a broadcast address. Ignored for a stream +be able to send packets to a broadcast address. This is ignored for a stream connection. @item :dontroute @var{dontroute-flag} @@ -2327,10 +2348,11 @@ If @var{linger-arg} is non-@code{nil}, wait for successful transmission of all queued packets on the connection before it is deleted (see @code{delete-process}). If @var{linger-arg} is an integer, it specifies the maximum time in seconds to wait for queued -packets to be sent before closing the connection. Default is -@code{nil} which means to discard unsent queued packets when the +packets to be sent before closing the connection. The default is +@code{nil}, which means to discard unsent queued packets when the process is deleted. +@c FIXME Where out-of-band data is ...? @item :oobinline @var{oobinline-flag} If @var{oobinline-flag} is non-@code{nil} for a stream connection, receive out-of-band data in the normal data stream. Otherwise, ignore @@ -2339,7 +2361,7 @@ out-of-band data. @item :priority @var{priority} Set the priority for packets sent on this connection to the integer @var{priority}. The interpretation of this number is protocol -specific, such as setting the TOS (type of service) field on IP +specific; such as setting the TOS (type of service) field on IP packets sent on this connection. It may also have system dependent effects, such as selecting a specific output queue on the network interface. @@ -2347,20 +2369,20 @@ interface. @item :reuseaddr @var{reuseaddr-flag} If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream server process, allow this server to reuse a specific port number (see -@code{:service}) unless another process on this host is already +@code{:service}), unless another process on this host is already listening on that port. If @var{reuseaddr-flag} is @code{nil}, there may be a period of time after the last use of that port (by any -process on the host), where it is not possible to make a new server on +process on the host) where it is not possible to make a new server on that port. @end table @defun set-network-process-option process option value &optional no-error This function sets or modifies a network option for network process -@var{process}. See @code{make-network-process} for details of options -@var{option} and their corresponding values @var{value}. If -@var{no-error} is non-@code{nil}, this function returns @code{nil} -instead of signaling an error if @var{option} is not a supported -option. If the function successfully completes, it returns @code{t}. +@var{process}. The accepted options and values are as for +@code{make-network-process}. If @var{no-error} is non-@code{nil}, +this function returns @code{nil} instead of signaling an error if +@var{option} is not a supported option. If the function successfully +completes, it returns @code{t}. The current setting of an option is available via the @code{process-contact} function. @@ -2377,11 +2399,9 @@ The current setting of an option is available via the @end example @noindent -The result of the first form is @code{t} if it works to specify +The result of this form is @code{t} if it works to specify @var{keyword} with value @var{value} in @code{make-network-process}. -The result of the second form is @code{t} if @var{keyword} is -supported by @code{make-network-process}. Here are some of the -@var{keyword}---@var{value} pairs you can test in +Here are some of the @var{keyword}---@var{value} pairs you can test in this way. @table @code @@ -2405,20 +2425,10 @@ Non-@code{nil} if the system can select the port for a server. @end example @noindent -Here are some of the options you can test in this way. - -@table @code -@item :bindtodevice -@itemx :broadcast -@itemx :dontroute -@itemx :keepalive -@itemx :linger -@itemx :oobinline -@itemx :priority -@itemx :reuseaddr -That particular network option is supported by -@code{make-network-process} and @code{set-network-process-option}. -@end table +The accepted @var{keyword} values are @code{:bindtodevice}, etc. +For the complete list, @pxref{Network Options}. This form returns +non-@code{nil} if that particular network option is supported by +@code{make-network-process} (or @code{set-network-process-option}). @node Misc Network @section Misc Network Facilities @@ -2490,11 +2500,11 @@ lets you change the speed, bytesize, and other parameters. In a terminal window created by @code{serial-term}, you can click on the mode line for configuration. - A serial connection is represented by a process object which can be -used similar to a subprocess or network process. You can send and -receive data and configure the serial port. A serial process object -has no process ID, you can't send signals to it, and the status codes -are different from other types of processes. + A serial connection is represented by a process object, which can be +used in a similar way to a subprocess or network process. You can send and +receive data, and configure the serial port. A serial process object +has no process ID, however, and you can't send signals to it, and the +status codes are different from other types of processes. @code{delete-process} on the process object or @code{kill-buffer} on the process buffer close the connection, but this does not affect the device connected to the serial port. @@ -2502,15 +2512,17 @@ device connected to the serial port. The function @code{process-type} returns the symbol @code{serial} for a process object representing a serial port connection. - Serial ports are available on GNU/Linux, Unix, and Windows systems. + Serial ports are available on GNU/Linux, Unix, and MS Windows systems. @deffn Command serial-term port speed Start a terminal-emulator for a serial port in a new buffer. -@var{port} is the name of the serial port to which to connect. For -example, this could be @file{/dev/ttyS0} on Unix. On Windows, this +@var{port} is the name of the serial port to connect to. For +example, this could be @file{/dev/ttyS0} on Unix. On MS Windows, this could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in Lisp strings). +@c FIXME is 9600 still the most common value, or is it 115200 now? +@c (Same value, 9600, appears below as well.) @var{speed} is the speed of the serial port in bits per second. 9600 is a common value. The buffer is in Term mode; see @ref{Term Mode,,, emacs, The GNU Emacs Manual}, for the commands to use in that buffer. @@ -2519,25 +2531,27 @@ You can change the speed and the configuration in the mode line menu. @defun make-serial-process &rest args This function creates a process and a buffer. Arguments are specified -as keyword/argument pairs. Here's the list of the meaningful keywords: +as keyword/argument pairs. Here's the list of the meaningful +keywords, with the first two (@var{port} and @var{speed}) being mandatory: @table @code -@item :port @var{port}@r{ (mandatory)} +@item :port @var{port} This is the name of the serial port. On Unix and GNU systems, this is a file name such as @file{/dev/ttyS0}. On Windows, this could be @file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9} (double the backslashes in Lisp strings). -@item :speed @var{speed}@r{ (mandatory)} +@item :speed @var{speed} The speed of the serial port in bits per second. This function calls -@code{serial-process-configure} to handle the speed. +@code{serial-process-configure} to handle the speed; see the +following documentation of that function for more details. @item :name @var{name} The name of the process. If @var{name} is not given, @var{port} will serve as the process name as well. @item :buffer @var{buffer} -The buffer to associate with the process. The value could be either a +The buffer to associate with the process. The value can be either a buffer or a string that names a buffer. Process output goes at the end of that buffer, unless you specify an output stream or filter function to handle the output. If @var{buffer} is not given, the @@ -2547,16 +2561,16 @@ keyword. @item :coding @var{coding} If @var{coding} is a symbol, it specifies the coding system used for both reading and writing for this process. If @var{coding} is a cons -@code{(decoding . encoding)}, @var{decoding} is used for reading, and -@var{encoding} is used for writing. If not specified, the default is -to determine the coding systems from data itself. +@code{(@var{decoding} . @var{encoding})}, @var{decoding} is used for +reading, and @var{encoding} is used for writing. If not specified, +the default is to determine the coding systems from the data itself. @item :noquery @var{query-flag} Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}. The flags defaults to @code{nil} if unspecified. @item :stop @var{bool} -Start process in the @code{stopped} state if @var{bool} is +Start process in the ``stopped'' state if @var{bool} is non-@code{nil}. In the stopped state, a serial process does not accept incoming data, but you can send outgoing data. The stopped state is cleared by @code{continue-process} and set by @@ -2571,8 +2585,7 @@ Install @var{sentinel} as the process sentinel. @item :plist @var{plist} Install @var{plist} as the initial plist of the process. -@item :speed -@itemx :bytesize +@item :bytesize @itemx :parity @itemx :stopbits @itemx :flowcontrol @@ -2600,7 +2613,7 @@ Here is an example: This functions configures a serial port connection. Arguments are specified as keyword/argument pairs. Attributes that are not given are re-initialized from the process's current configuration (available -via the function @code{process-contact}) or set to reasonable default +via the function @code{process-contact}), or set to reasonable default values. The following arguments are defined: @table @code @@ -2618,8 +2631,8 @@ rate}. The value can be any number, but most serial ports work only at a few defined values between 1200 and 115200, with 9600 being the most common value. If @var{speed} is @code{nil}, the function ignores all other arguments and does not configure the port. This may be -useful for special serial ports such as Bluetooth-to-serial converters -which can only be configured through AT commands sent through the +useful for special serial ports such as Bluetooth-to-serial converters, +which can only be configured through @samp{AT} commands sent through the connection. The value of @code{nil} for @var{speed} is valid only for connections that were already opened by a previous call to @code{make-serial-process} or @code{serial-term}. @@ -2646,9 +2659,9 @@ flow control). If @var{flowcontrol} is not given, it defaults to no flow control. @end table -@code{serial-process-configure} is called by -@code{make-serial-process} for the initial configuration of the serial -port. +Internally, @code{make-serial-process} calls +@code{serial-process-configure} for the initial configuration of the +serial port. @end defun @node Byte Packing @@ -2658,8 +2671,12 @@ port. This section describes how to pack and unpack arrays of bytes, usually for binary network protocols. These functions convert byte arrays to alists, and vice versa. The byte array can be represented as a +@c FIXME? No multibyte? unibyte string or as a vector of integers, while the alist associates symbols either with fixed-size objects or with recursive sub-alists. +To use the functions referred to in this section, load the +@code{bindat} library. +@c It doesn't have any autoloads. @cindex serializing @cindex deserializing @@ -2680,7 +2697,7 @@ direction is also known as @dfn{serializing} or @dfn{packing}. To control unpacking and packing, you write a @dfn{data layout specification}, a special nested list describing named and typed -@dfn{fields}. This specification controls length of each field to be +@dfn{fields}. This specification controls the length of each field to be processed, and how to pack or unpack it. We normally keep bindat specs in variables whose names end in @samp{-bindat-spec}; that kind of name is automatically recognized as ``risky''. @@ -2729,12 +2746,12 @@ String of length @var{len}. Zero-terminated string, in a fixed-size field with length @var{len}. @item vec @var{len} [@var{type}] -Vector of @var{len} elements of type @var{type}, or bytes if not -@var{type} is specified. +Vector of @var{len} elements of type @var{type}, defaulting to bytes. The @var{type} is any of the simple types above, or another vector -specified as a list @code{(vec @var{len} [@var{type}])}. +specified as a list of the form @code{(vec @var{len} [@var{type}])}. @item ip +@c FIXME? IPv6? Four-byte vector representing an Internet address. For example: @code{[127 0 0 1]} for localhost. @@ -2762,12 +2779,11 @@ below, or by an expression @code{(eval @var{form})} where @var{form} should evaluate to an integer, specifying the field length. A field specification generally has the form @code{([@var{name}] -@var{handler})}. The square braces indicate that @var{name} is -optional. (Don't use names that are symbols meaningful as type -specifications (above) or handler specifications (below), since that -would be ambiguous.) @var{name} can be a symbol or the expression -@code{(eval @var{form})}, in which case @var{form} should evaluate to -a symbol. +@var{handler})}, where @var{name} is optional. Don't use names that +are symbols meaningful as type specifications (above) or handler +specifications (below), since that would be ambiguous. @var{name} can +be a symbol or an expression @code{(eval @var{form})}, in which case +@var{form} should evaluate to a symbol. @var{handler} describes how to unpack or pack the field and can be one of the following: @@ -2814,10 +2830,11 @@ of @var{form}. A non-@code{nil} result indicates a match. @item repeat @var{count} @var{field-specs}@dots{} Process the @var{field-specs} recursively, in order, then repeat -starting from the first one, processing all the specs @var{count} +starting from the first one, processing all the specifications @var{count} times overall. The @var{count} is given using the same formats as a field length---if an @code{eval} form is used, it is evaluated just once. -For correct operation, each spec in @var{field-specs} must include a name. +For correct operation, each specification in @var{field-specs} must +include a name. @end table For the @code{(eval @var{form})} forms used in a bindat specification, @@ -2856,9 +2873,10 @@ specification, @code{bindat-raw} to a byte array, and @var{struct} to an alist representing unpacked field data. @defun bindat-unpack spec bindat-raw &optional bindat-idx +@c FIXME? Again, no multibyte? This function unpacks data from the unibyte string or byte array @code{bindat-raw} -according to @var{spec}. Normally this starts unpacking at the +according to @var{spec}. Normally, this starts unpacking at the beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it specifies a zero-based starting position to use instead. @@ -2894,7 +2912,7 @@ according to @var{spec}. @defun bindat-pack spec struct &optional bindat-raw bindat-idx This function returns a byte array packed according to @var{spec} from -the data in the alist @var{struct}. Normally it creates and fills a +the data in the alist @var{struct}. It normally creates and fills a new byte array starting at the beginning. However, if @var{bindat-raw} is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting @@ -2907,6 +2925,7 @@ meets or exceeds the total length to avoid an out-of-range error. @defun bindat-ip-to-string ip Convert the Internet address vector @var{ip} to a string in the usual dotted notation. +@c FIXME? Does it do IPv6? @example (bindat-ip-to-string [127 0 0 1]) @@ -2916,10 +2935,16 @@ dotted notation. @node Bindat Examples @subsection Examples of Byte Unpacking and Packing +@c FIXME? This seems a very long example for something that is not used +@c very often. As of 24.1, gdb-mi.el is the only user of bindat.el in Emacs. +@c Maybe one or both of these examples should just be moved to the +@c commentary of bindat.el. Here is a complete example of byte unpacking and packing: @lisp +(require 'bindat) + (defvar fcookie-index-spec '((:version u32) (:count u32) @@ -2928,16 +2953,14 @@ dotted notation. (:flags u32) (:delim u8) (:ignored fill 3) - (:offset repeat (:count) - (:foo u32))) + (:offset repeat (:count) (:foo u32))) "Description of a fortune cookie index file's contents.") (defun fcookie (cookies &optional index) "Display a random fortune cookie from file COOKIES. Optional second arg INDEX specifies the associated index -filename, which is by default constructed by appending -\".dat\" to COOKIES. Display cookie text in possibly -new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME +filename, by default \"COOKIES.dat\". Display cookie text +in buffer \"*Fortune Cookie: BASENAME*\", where BASENAME is COOKIES without the directory part." (interactive "fCookies file: ") (let* ((info (with-temp-buffer @@ -2960,10 +2983,9 @@ is COOKIES without the directory part." (defun fcookie-create-index (cookies &optional index delim) "Scan file COOKIES, and write out its index file. -Optional second arg INDEX specifies the index filename, -which is by default constructed by appending \".dat\" to -COOKIES. Optional third arg DELIM specifies the unibyte -character which, when found on a line of its own in +Optional arg INDEX specifies the index filename, which by +default is \"COOKIES.dat\". Optional arg DELIM specifies the +unibyte character that, when found on a line of its own in COOKIES, indicates the border between entries." (interactive "fCookies file: ") (setq delim (or delim ?%)) @@ -3000,8 +3022,8 @@ COOKIES, indicates the border between entries." (write-file (or index (concat cookies ".dat"))))))) @end lisp -Following is an example of defining and unpacking a complex structure. -Consider the following C structures: +The following is an example of defining and unpacking a complex +structure. Consider the following C structures: @example struct header @{ @@ -3014,14 +3036,14 @@ struct header @{ struct data @{ unsigned char type; unsigned char opcode; - unsigned short length; /* In network byte order */ + unsigned short length; /* in network byte order */ unsigned char id[8]; /* null-terminated string */ unsigned char data[/* (length + 3) & ~3 */]; @}; struct packet @{ struct header header; - unsigned long counters[2]; /* In little endian order */ + unsigned long counters[2]; /* in little endian order */ unsigned char items; unsigned char filler[3]; struct data item[/* items */]; @@ -3029,7 +3051,7 @@ struct packet @{ @}; @end example -The corresponding data layout specification: +The corresponding data layout specification is: @lisp (setq header-spec @@ -3041,21 +3063,21 @@ The corresponding data layout specification: (setq data-spec '((type u8) (opcode u8) - (length u16) ;; network byte order + (length u16) ; network byte order (id strz 8) (data vec (length)) (align 4))) (setq packet-spec '((header struct header-spec) - (counters vec 2 u32r) ;; little endian order + (counters vec 2 u32r) ; little endian order (items u8) (fill 3) (item repeat (items) (struct data-spec)))) @end lisp -A binary data representation: +A binary data representation is: @lisp (setq binary-data @@ -3065,7 +3087,7 @@ A binary data representation: 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) @end lisp -The corresponding decoded structure: +The corresponding decoded structure is: @lisp (setq decoded (bindat-unpack packet-spec binary-data)) @@ -3089,7 +3111,7 @@ The corresponding decoded structure: (type . 1)))) @end lisp -Fetching data from this structure: +An example of fetching data from this structure: @lisp (bindat-get-field decoded 'item 1 'id) diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 45a0dee3b1c..25ea8577467 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -658,8 +658,8 @@ Minibuffers * Multiple Queries:: Asking a series of similar questions. * Reading a Password:: Reading a password from the terminal. * Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Contents:: How such commands access the minibuffer text. * Minibuffer Windows:: Operating on the special minibuffer windows. +* Minibuffer Contents:: How such commands access the minibuffer text. * Recursive Mini:: Whether recursive entry to minibuffer is allowed. * Minibuffer Misc:: Various customization hooks and variables. @@ -670,7 +670,7 @@ Completion * Minibuffer Completion:: Invoking the minibuffer with completion. * Completion Commands:: Minibuffer commands that do completion. * High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.). + (reading buffer names, variable names, etc.). * Reading File Names:: Using completion to read file names and shell commands. * Completion Variables:: Variables controlling completion behavior. diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index 01a3e3c129e..2fd2a8d8224 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -657,8 +657,8 @@ Minibuffers * Multiple Queries:: Asking a series of similar questions. * Reading a Password:: Reading a password from the terminal. * Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Contents:: How such commands access the minibuffer text. * Minibuffer Windows:: Operating on the special minibuffer windows. +* Minibuffer Contents:: How such commands access the minibuffer text. * Recursive Mini:: Whether recursive entry to minibuffer is allowed. * Minibuffer Misc:: Various customization hooks and variables. @@ -669,7 +669,7 @@ Completion * Minibuffer Completion:: Invoking the minibuffer with completion. * Completion Commands:: Minibuffer commands that do completion. * High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.). + (reading buffer names, variable names, etc.). * Reading File Names:: Using completion to read file names and shell commands. * Completion Variables:: Variables controlling completion behavior. diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 46fea77107b..20c453544bc 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,23 @@ +2012-04-20 Glenn Morris <rgm@gnu.org> + + * faq.texi (New in Emacs 24): New section. + (Packages that do not come with Emacs): Mention M-x list-packages. + +2012-04-20 Glenn Morris <rgm@gnu.org> + + * Makefile.in: Replace non-portable use of $< in emacs-gnutls rules. + +2012-04-20 Eli Zaretskii <eliz@gnu.org> + + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add emacs-gnutls. + ($(infodir)/emacs-gnutls, emacs-gnutls.dvi): New targets. + +2012-04-20 Teodor Zlatanov <tzz@lifelogs.com> + + * emacs-gnutls.texi: Add documentation for the GnuTLS integration. + * Makefile.in: Add emacs-gnutls.texi to build. + +2012-04-20 Alan Mackenzie <acm@muc.de> 2012-04-14 Alan Mackenzie <acm@muc.de> * cc-mode.texi (c-offsets-alist): Correct a typo. diff --git a/doc/misc/faq.texi b/doc/misc/faq.texi index 5b7bb7ec9ce..0f20c41c8eb 100644 --- a/doc/misc/faq.texi +++ b/doc/misc/faq.texi @@ -942,6 +942,7 @@ status of its latest version. @menu * Origin of the term Emacs:: * Latest version of Emacs:: +* New in Emacs 24:: * New in Emacs 23:: * New in Emacs 22:: * New in Emacs 21:: @@ -1009,12 +1010,84 @@ Emacs, type @kbd{C-h C-n} (@kbd{M-x view-emacs-news}). As of Emacs 22, you can give this command a prefix argument to read about which features were new in older versions. +@node New in Emacs 24 +@section What is different about Emacs 24? +@cindex Differences between Emacs 23 and Emacs 24 +@cindex Emacs 24, new features in + +@itemize +@cindex packages, installing more +@item +Emacs now includes a package manager. Type @kbd{M-x list-packages} to +get started. You can use this to download and automatically install +many more Lisp packages. + +@cindex lexical binding +@item +Emacs Lisp now supports lexical binding on a per-file basis. In +@emph{lexical binding}, variable references must be located textually +within the binding construct. This contrasts with @emph{dynamic +binding}, where programs can refer to variables defined outside their +local textual scope. A Lisp file can use a local variable setting of +@code{lexical-binding: t} to indicate that the contents should be +interpreted using lexical binding. See the Emacs Lisp Reference +Manual for more details. + +@cindex bidirectional display +@cindex right-to-left languages +@item +Some human languages, such as English, are written from left to right. +Others, such as Arabic, are written from right to left. Emacs now has +support for any mixture of these forms---this is ``bidirectional text''. + +@item +Handling of text selections has been improved, and now integrates +better with external clipboards. + +@cindex themes +@item +A new command @kbd{customize-themes} allows you to easily change the +appearance of your Emacs. + +@item +Emacs can be compiled with the Gtk+ 3 toolkit. + +@item +Support for several new external libraries can be included at compile +time: + +@itemize + +@item +``Security-Enhanced Linux'' (SELinux) is a Linux kernel feature that +provides more sophisticated file access controls than ordinary +``Unix-style'' file permissions. + +@item +The ImageMagick display library. This allows you to display many more +image format in Emacs, as well as carry out transformations such as +rotations. + +@item +The GnuTLS library for secure network communications. Emacs uses this +transparently for email if your mail server supports it. + +@item +The libxml2 library for parsing XML structures. +@end itemize + +@item +Much more flexibility in the handling of windows and buffer display. + +@end itemize + +As always, consult the @file{NEWS} file for more information. + + @node New in Emacs 23 @section What is different about Emacs 23? @cindex Differences between Emacs 22 and Emacs 23 @cindex Emacs 23, new features in -@cindex Recently introduced features -@cindex Default features @itemize @@ -1065,8 +1138,7 @@ Other changes include: support for serial port access; D-Bus bindings; a new Visual Line mode for line-motion; improved completion; a new mode (@samp{DocView}) for viewing of PDF, PostScript, and DVI documents; nXML mode (for editing XML documents) is included; VC has been updated for -newer version control systems; etc. As always, consult the @file{NEWS} -file for more information. +newer version control systems; etc. @node New in Emacs 22 @@ -3225,6 +3297,14 @@ see @ref{Packages that do not come with Emacs}. @cindex Emacs Lisp List @cindex Emacs Lisp Archive +Your first port of call should be the @kbd{M-x list-packages} command. +This connects to the @uref{http:///elpa.gnu.org, GNU ELPA} (``Emacs +Lisp Package Archive'') server and fetches the list of additional +packages that it offers. These are GNU packages that are available +for use with Emacs, but are distributed separately. Select a package +to get more details about the features that it offers, and then if you +wish, Emacs can download and automatically install it for you. + @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs Lisp List (ELL)}, maintained by @email{S.J.Eglen@@damtp.cam.ac.uk, Stephen Eglen}, aims to provide one compact list with links to all of the current Emacs diff --git a/etc/CONTRIBUTE b/etc/CONTRIBUTE index 06b9a9e45a5..aff350f9642 100644 --- a/etc/CONTRIBUTE +++ b/etc/CONTRIBUTE @@ -1,4 +1,4 @@ -Copyright (C) 2006-2012 Free Software Foundation, Inc. +Copyright (C) 2006-2012 Free Software Foundation, Inc. See end for license conditions. @@ -44,13 +44,24 @@ Ref: The "Tips" Appendix in the Emacs Lisp Reference. * Copyright Assignment -We can accept small changes (roughly, fewer than 15 lines) without -legal papers. Anything more substantial requires a copyright -disclaimer or assignment (the latter is preferred, especially for -larger changes). Both of these involved filling out a short form and -filing it with the FSF. The process is straightforward -- contact us -at emacs-devel@gnu.org to obtain the relevant forms. +The FSF (Free Software Foundation) is the copyright holder for GNU Emacs. +The FSF is a nonprofit with a worldwide mission to promote computer +user freedom and to defend the rights of all free software users. +For general information, see the website http://www.fsf.org/ . + +Generally speaking, for non-trivial contributions to GNU Emacs we +require that the copyright be assigned to the FSF. For the reasons +behind this, see: http://www.gnu.org/licenses/why-assign.html . +Copyright assignment is a simple process. If you live in the US, you +can do it entirely electronically. We can help you get started, and +answer any questions you may have (or point you to the people with the +answers), at the emacs-devel@gnu.org mailing list. + +A copyright disclaimer is also a possibility, but we prefer an assignment. +We can accept small changes (roughly, fewer than 15 lines) without +an assignment. This is a cumulative limit (e.g. three separate 5 line +patches) over all your contributions. * Getting the Source Code diff --git a/etc/ChangeLog b/etc/ChangeLog index 9353b617cb2..f2cdfb83c44 100644 --- a/etc/ChangeLog +++ b/etc/ChangeLog @@ -1,3 +1,9 @@ +2012-04-20 Glenn Morris <rgm@gnu.org> + + * CONTRIBUTE: Expand a bit on copyright assignments. + + * MORE.STUFF: General update. Mention list-packages. + Remove many old/outdated URLs. 2012-04-10 Lars Magne Ingebrigtsen <larsi@gnus.org> * publicsuffix.txt: New file (bug#1401). diff --git a/etc/MORE.STUFF b/etc/MORE.STUFF index 84a34d24585..06e0870e4ce 100644 --- a/etc/MORE.STUFF +++ b/etc/MORE.STUFF @@ -1,99 +1,87 @@ More Neat Stuff for your Emacs -Copyright (C) 1993, 1999, 2001-2012 Free Software Foundation, Inc. +Copyright (C) 1993, 1999, 2001-2012 Free Software Foundation, Inc. See the end of the file for license conditions. -This file describes GNU Emacs programs and resources that are -maintained by other people. Some of these may become part of the -Emacs distribution in the future. Others we unfortunately can't -distribute, even though they are free software, because we lack legal -papers for copyright purposes. Also included are sites where -development versions of some packages distributed with Emacs may be -found. +The easiest way to add more features to your Emacs is to use the command +M-x list-packages. This contacts the server at <URL:http://elpa.gnu.org>, +where many Emacs Lisp packages are stored. These are distributed +separately from Emacs itself for reasons of space, etc. You can browse +the resulting *Packages* buffer to see what is available, and then +Emacs can automatically download and install the packages that you +select. See the section "Emacs Lisp Packages" in the Emacs manual +for more details. -You might also look at the Emacs web page -<URL:http://www.gnu.org/software/emacs/emacs.html>. If you use the -Windows-32 version of Emacs, see the NTEmacs sites listed in the FAQ. +Below we describe some GNU Emacs programs and resources that are +maintained by other people. Some of these may become part of the +Emacs distribution, or GNU ELPA, in the future. Others we unfortunately +can't distribute, even though they are free software, because we lack +legal papers for copyright purposes. -Please submit a bug report if you find that any of the addresses -listed here fail. +Also listed are sites where development versions of some packages +distributed with Emacs may be found. -* The `Emacs Lisp List' at - <URL:http://www.damtp.cam.ac.uk/user/eglen/emacs/ell.html> has pointers - to sources of a large number of packages. +It is difficult to keep this file up-to-date, and it only lists a fraction +of the Emacs modes that are available. If you are interested in +a particular feature, then after checking Emacs itself and GNU ELPA, +a web search is often the best way to find results. -* gnu.emacs.sources +* The gnu-emacs-sources mailing list + <URL:https://lists.gnu.org/mailman/listinfo/gnu-emacs-sources> + which is gatewayed to the gnu.emacs.sources newsgroup (although the + connection between the two can be unreliable) is an official + place where people can post or announce their extensions to Emacs. -Packages posted to the gnu.emacs.sources newsgroup (see -etc/MAILINGLISTS) might be archived specifically (try a web search -engine) or retrievable from general Usenet archive services. +* The `Emacs Lisp List' at + <URL:http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html> has pointers + to sources of a large number of packages. Unfortunately, at the time + of writing it seems to no longer be updating. * emacswiki.org + The Emacs Wiki has an area for storing elisp files + <URL:http://www.emacswiki.org/cgi-bin/wiki/ElispArea>. -The Emacs Wiki has an area for storing elisp files -<URL:http://www.emacswiki.org/cgi-bin/wiki/ElispArea>. - -* Emacs tutorials and manuals +* WikEmacs + <URL:http://wikemacs.org> is an alternative wiki for Emacs. - * Emacs slides and tutorials can be found here: +* Emacs slides and tutorials can be found here: <URL:http://web.psung.name/emacs/> * Maintenance versions of some packages distributed with Emacs You might find bug-fixes or enhancements in these places. +In many cases, however, development of these packages has shifted to Emacs, +so you will find the latest version in Emacs. * Ada-mode: <URL:http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html> * Battery and Info Look: <URL:http://ralph-schleicher.de/emacs.html> - * BS: <URL:http://www.geekware.de/software/emacs/index.html> - - * Calculator: <URL:http://www.barzilay.org/misc/calculator.el> - * CC mode: <URL:http://cc-mode.sourceforge.net/> * CPerl: <URL:http://math.berkeley.edu/~ilya/software/emacs/> * Ediff and Viper: <URL:http://www.cs.sunysb.edu/~kifer/emacs.html> - * Eldoc and Rlogin: - <URL:http://www.splode.com/~friedman/software/emacs-lisp/> - * ERC: <URL:http://savannah.gnu.org/projects/erc/> - * Etags: <URL:http://fly.isti.cnr.it/software/> - * Gnus: <URL:http://www.gnus.org/> - * Ispell: <URL:http://www.kdstevens.com/stevens/ispell-page.html> - * MH-E: <URL:http://mh-e.sourceforge.net/> * nXML: <URL:http://www.thaiopensource.com/nxml-mode/> * Org mode: <URL:http://orgmode.org/> - * PS mode: <URL:http://odur.let.rug.nl/%7Ekleiweg/postscript/> - - * PS-print: <URL:http://www.emacswiki.org/cgi-bin/wiki/PsPrintPackage> - - * Python: <URL:http://www.loveshack.ukfsn.org/emacs/> - - * QuickURL: <URL:http://www.davep.org/emacs/> - * RefTeX: <URL:http://www.gnu.org/software/auctex/reftex.html> * Remember: <URL:https://gna.org/p/remember-el> - * Speedbar, Checkdoc etc: <URL:http://cedet.sourceforge.net/> - - * SQL: <URL:http://www.emacswiki.org/cgi-bin/wiki/sql.el> + * CEDET: <URL:http://cedet.sourceforge.net/> * Tramp: Remote file access via rsh/ssh <URL:http://savannah.gnu.org/projects/tramp/> - * Webjump: <URL:http://www.neilvandyke.org/webjump> - * Auxiliary files * (Tex)info files for use with Info-look that don't come from GNU @@ -114,18 +102,16 @@ Emacs for various reasons, sometimes because their authors haven't made a copyright assignment to the FSF. Some of them may be integrated in the future. -You might like to check whether they are packaged for your system. -Several are for Debian GNU/Linux in particular. +Your operating system distribution may include several of these as optional +packages that you can install. * AUCTeX: <URL:http://www.gnu.org/software/auctex/> An extensible package that supports writing and formatting TeX files (including AMS-TeX, LaTeX, Texinfo, ConTeXt, and docTeX). + Available from GNU ELPA. * BBDB: personal Info Rolodex integrated with mail/news: - <URL:http://bbdb.sourceforge.net/> - [You might want to set the coding system of your .bbdb file to - emacs-mule, say by adding `("\\.bbdb\\'" . emacs-mule)' to - `file-coding-system-alist' for non-ASCII characters.] + <URL:http://savannah.nongnu.org/projects/bbdb> * Boxquote: <URL:http://www.davep.org/emacs/> @@ -143,13 +129,6 @@ Several are for Debian GNU/Linux in particular. * Ee: categorizing information manager: <URL:http://www.jurta.org/en/emacs/ee/> - * EFS: enhanced version of ange-ftp: - <URL:http://www-pu.informatik.uni-tuebingen.de/users/sperber/software/efs/> - - * Elib library: <URL:http://www.gnu.org/software/elib/elib.html> - From GNU distribution mirrors. (Much of this functionality is now - in Emacs.) - * EMacro: <URL:http://emacro.sourceforge.net/> EMacro is a portable configuration file that configures itself. @@ -168,33 +147,19 @@ Several are for Debian GNU/Linux in particular. * Emacs Wiki Mode: <URL:http://mwolson.org/projects/EmacsWikiMode.html> A wiki-like publishing tool and personal information manager - * Gnuserv: - <URL:http://www.hpl.hp.com/personal/ange/gnuserv/home.html> - Alternative emacsclient/emacsserver. Also available from this Web - page: eiffel-mode.el. - * Go in a buffer: Go Text Protocol client: <URL:http://www.gnuvola.org/software/personal-elisp/dist/lisp/diversions/gnugo.el> A modified version is also bundled with GNU Go: <URL:http://www.gnu.org/software/gnugo/gnugo.html> - * hm--html-menus: - <URL:ftp://sunsite.unc.edu/pub/Linux/apps/editors/emacs/> - HTML-specific editing. Can work with PSGML. - * Hyperbole: - <URL:http://directory.fsf.org/hyperbole.html> + <URL:http://directory.fsf.org/wiki/Hyperbole> Hyperbole is an open, efficient, programmable information management and hypertext system. * JDEE: <URL:http://jdee.sourceforge.net/> Provides a Java development environment for Emacs. - * Mailcrypt: - <URL:http://mailcrypt.sourceforge.net/> - PGP and GPG support. PGP isn't free software, but GPG, the GNU - Privacy Guard, is a free replacement <URL:http://www.gnupg.org/>. - * Mew: <URL:http://www.mew.org/> A MIME mail reader for Emacs/XEmacs. @@ -208,9 +173,6 @@ Several are for Debian GNU/Linux in particular. * Preview LaTeX: embed preview LaTeX images in source buffer. <URL:http://www.gnu.org/software/auctex/preview-latex.html> - * PSGML: <URL:http://www.lysator.liu.se/projects/about_psgml.html> - DTD-aware serious SGML/XML editing. - * Quack: <URL:http://www.neilvandyke.org/quack/> Quack enhances Emacs support for Scheme. @@ -227,26 +189,17 @@ Several are for Debian GNU/Linux in particular. * Tamago: Chinese/Japanese/Korean input method <URL:http://www.m17n.org/tamago/index.en.html> Emacs Lisp package to provide input methods for CJK characters. - It can use these background conversion servers: - FreeWnn (jserver, cserver, tserver), - Wnn6, - SJ3 Ver.2 - * Tiny Tools: <URL:http://freshmeat.net/projects/emacs-tiny-tools> + * Tiny Tools: <URL:https://savannah.nongnu.org/projects/emacs-tiny-tools> * VM (View Mail): Alternative mail reader <URL:http://launchpad.net/vm> Previously hosted at: <URL:http://www.nongnu.org/viewmail/> - There are VM newsgroups: <URL:news:gnu.emacs.vm.info>, and - <URL:news:gnu.emacs.vm.bug>. - * W3: <URL:http://savannah.gnu.org/projects/w3/> - Web browser. There's a W3 mail list/newsgroup - <URL:http://savannah.gnu.org/mail/?group=w3>. + * W3 Web browser: <URL:http://savannah.gnu.org/projects/w3/> * Wanderlust: <URL:http://www.gohome.org/wl/> - Yet Another Message Interface on Emacsen. Wanderlust is a mail/news - reader supporting IMAP4rev1 for emacsen. + Wanderlust is a mail/news reader for Emacs. * WhizzyTex: <URL:http://cristal.inria.fr/whizzytex/> WhizzyTeX provides a minor mode for Emacs or XEmacs, a (bash) diff --git a/lib-src/ChangeLog b/lib-src/ChangeLog index 106b2c8faca..c76303d8fa2 100644 --- a/lib-src/ChangeLog +++ b/lib-src/ChangeLog @@ -1,3 +1,8 @@ +2012-04-20 Chong Yidong <cyd@gnu.org> + + * emacsclient.c (decode_options): Move -t -n corner case handling + into server.el (Bug#11102). + 2012-04-18 Paul Eggert <eggert@cs.ucla.edu> configure: new option --enable-gcc-warnings (Bug#11207) diff --git a/lib-src/emacsclient.c b/lib-src/emacsclient.c index 05fd0f3515e..48b4384d487 100644 --- a/lib-src/emacsclient.c +++ b/lib-src/emacsclient.c @@ -638,32 +638,23 @@ decode_options (int argc, char **argv) if (display && strlen (display) == 0) display = NULL; -#ifdef WINDOWSNT - /* Emacs on Windows does not support GUI and console frames in the same - instance. So, it makes sense to treat the -t and -c options as - equivalent, and open a new frame regardless of whether the running - instance is GUI or console. Ideally, we would only set tty = 1 when - the instance is running in a console, but alas we don't know that. - The simplest workaround is to always ask for a tty frame, and let - server.el check whether it makes sense. */ - if (tty || !current_frame) - { - display = (const char *) ttyname (0); /* Arg is ignored. */ - current_frame = 0; - tty = 1; - } -#endif - /* If no display is available, new frames are tty frames. */ if (!current_frame && !display) tty = 1; - /* --no-wait implies --current-frame on ttys when there are file - arguments or expressions given. */ - if (nowait && tty && argc - optind > 0) - current_frame = 1; - #ifdef WINDOWSNT + /* Emacs on Windows does not support graphical and text terminal + frames in the same instance. So, treat the -t and -c options as + equivalent, and open a new frame on the server's terminal. + Ideally, we would only set tty = 1 when the serve is running in a + console, but alas we don't know that. As a workaround, always + ask for a tty frame, and let server.el figure it out. */ + if (!current_frame) + { + display = NULL; + tty = 1; + } + if (alternate_editor && alternate_editor[0] == '\0') { message (TRUE, "--alternate-editor argument or ALTERNATE_EDITOR variable cannot be\n\ diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 42f99ec9c9e..c9cece95445 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,77 @@ +2012-04-20 Dan Nicolaescu <dann@gnu.org> + + * battery.el (battery-echo-area-format): Display remaining time + for sysfs backend too (Bug#11269). + (battery-linux-sysfs): Fix conditional for the charge. + +2012-04-20 Chong Yidong <cyd@gnu.org> + + * progmodes/gdb-mi.el (gdb): Revert previous change. + (gdb-inferior-io--init-proc): New function. + (gdb-init-1): Use it. + (gdb-inferior-io-sentinel): New sentinel for the gdb-inferior pty, + responsible for allocating a new pty and hooking it to gdb when + the old pty gets an EIO due to process exit. + (gdb-delchar-or-quit): New command. Bind it in gdb-mi buffers. + (gdb-tooltip-print): Don't use obsolete tooltip-use-echo-area. + (gdb-inferior-io--maybe-delete-pty): Move into gdb-reset. + +2012-04-20 Eli Zaretskii <eliz@gnu.org> + + * window.el (window-min-size, window-sizable, window-min-delta) + (window-max-delta, window--resizable, window-resizable) + (window-total-size, window-full-height-p, window-full-width-p) + (window-in-direction, window--resize-mini-window, window-resize) + (window--resize-child-windows-normal) + (window--resize-child-windows, window--resize-siblings) + (window--resize-this-window, adjust-window-trailing-edge) + (enlarge-window, shrink-window): Doc fixes. + +2012-04-20 Chong Yidong <cyd@gnu.org> + + * progmodes/gdb-mi.el (gdb-inferior-io--maybe-delete-pty): New + function to call delete-process on the gdb-inferior buffer's pty. + (gdb-reset): Use it, instead of relying on kill-buffer to kill the + pty process (Bug#11273). + (gdb-update): New arg to suppress talking to the gdb process. + (gdb-done-or-error): Use it. + (gdb-stopped-functions): Rename from gdb-stopped-hooks. + (gdb): Call gdb-inferior-io--maybe-delete-pty as a workaround for + sentinel not being called. + + * comint.el (make-comint-in-buffer, comint-exec): Doc fix. + + * progmodes/grep.el (grep, rgrep): Doc fix (Bug#11268). + +2012-04-20 Glenn Morris <rgm@gnu.org> + + * net/network-stream.el (open-network-stream): Doc fix. + +2012-04-20 Chong Yidong <cyd@gnu.org> + + * emacs-lisp/tabulated-list.el (tabulated-list-print): Fix typos. + +2012-04-20 Alan Mackenzie <acm@muc.de> + + Ensure searching for keywords is case sensitive. + + * progmodes/cc-cmds.el (c-electric-brace, c-electric-lt-gt) + (c-electric-paren, c-beginning-of-defun, c-end-of-defun) + (c-defun-name, c-mark-function, c-cpp-define-name) + (c-comment-indent, c-scan-conditionals, c-indent-defun) + (c-context-line-break): Bind case-fold-search to nil. + + * progmodes/cc-mode.el (c-font-lock-fontify-region): Bind + case-fold-search to nil. + +2012-04-20 Chong Yidong <cyd@gnu.org> + + * mail/sendmail.el (mail-bury): Call return action with the right + Rmail buffer (Bug#11242). + + * server.el (server-process-filter): Handle corner case where both + tty and nowait options are present (Bug#11102). + 2012-04-20 Eli Zaretskii <eliz@gnu.org> * version.el (emacs-bzr-version, emacs-bzr-get-version): Doc fixes. diff --git a/lisp/battery.el b/lisp/battery.el index 78898534a47..dcfe07121b3 100644 --- a/lisp/battery.el +++ b/lisp/battery.el @@ -78,7 +78,7 @@ introduced by a `%' character in a control string." (cond ((eq battery-status-function 'battery-linux-proc-acpi) "Power %L, battery %B at %r (%p%% load, remaining time %t)") ((eq battery-status-function 'battery-linux-sysfs) - "Power %L, battery %B (%p%% load)") + "Power %L, battery %B (%p%% load, remaining time %t)") ((eq battery-status-function 'battery-pmset) "%L power, battery %B (%p%% load, remaining time %t)") (battery-status-function @@ -509,7 +509,7 @@ The following %-sequences are provided: "N/A")) (cons ?d (or temperature "N/A")) (cons ?B (or charging-state "N/A")) - (cons ?p (cond ((> charge-full 0) + (cons ?p (cond ((and (> charge-full 0) (> charge-now 0)) (format "%.1f" (/ (* 100 charge-now) charge-full))) ((> energy-full 0) diff --git a/lisp/comint.el b/lisp/comint.el index 68fedeb88a9..10981675971 100644 --- a/lisp/comint.el +++ b/lisp/comint.el @@ -699,16 +699,21 @@ BUFFER can be either a buffer or the name of one." (defun make-comint-in-buffer (name buffer program &optional startfile &rest switches) "Make a Comint process NAME in BUFFER, running PROGRAM. If BUFFER is nil, it defaults to NAME surrounded by `*'s. -PROGRAM should be either a string denoting an executable program to create -via `start-file-process', or a cons pair of the form (HOST . SERVICE) denoting -a TCP connection to be opened via `open-network-stream'. If there is already -a running process in that buffer, it is not restarted. Optional fourth arg -STARTFILE is the name of a file, whose contents are sent to the -process as its initial input. +If there is a running process in BUFFER, it is not restarted. + +PROGRAM should be one of the following: +- a string, denoting an executable program to create via + `start-file-process' +- a cons pair of the form (HOST . SERVICE), denoting a TCP + connection to be opened via `open-network-stream' +- nil, denoting a newly-allocated pty. + +Optional fourth arg STARTFILE is the name of a file, whose +contents are sent to the process as its initial input. If PROGRAM is a string, any more args are arguments to PROGRAM. -Returns the (possibly newly created) process buffer." +Return the (possibly newly created) process buffer." (or (fboundp 'start-file-process) (error "Multi-processing is not supported for this system")) (setq buffer (get-buffer-create (or buffer (concat "*" name "*")))) @@ -752,9 +757,18 @@ See `make-comint' and `comint-exec'." (defun comint-exec (buffer name command startfile switches) "Start up a process named NAME in buffer BUFFER for Comint modes. Runs the given COMMAND with SWITCHES, and initial input from STARTFILE. -Blasts any old process running in the buffer. Doesn't set the buffer mode. -You can use this to cheaply run a series of processes in the same Comint -buffer. The hook `comint-exec-hook' is run after each exec." + +COMMAND should be one of the following: +- a string, denoting an executable program to create via + `start-file-process' +- a cons pair of the form (HOST . SERVICE), denoting a TCP + connection to be opened via `open-network-stream' +- nil, denoting a newly-allocated pty. + +This function blasts any old process running in the buffer, and +does not set the buffer mode. You can use this to cheaply run a +series of processes in the same Comint buffer. The hook +`comint-exec-hook' is run after each exec." (with-current-buffer buffer (let ((proc (get-buffer-process buffer))) ; Blast any old process. (if proc (delete-process proc))) diff --git a/lisp/emacs-lisp/tabulated-list.el b/lisp/emacs-lisp/tabulated-list.el index f17b12da6a0..9439fba2b86 100644 --- a/lisp/emacs-lisp/tabulated-list.el +++ b/lisp/emacs-lisp/tabulated-list.el @@ -215,7 +215,7 @@ buffer and inserts the entries with `tabulated-list-printer'. Optional argument REMEMBER-POS, if non-nil, means to move point to the entry with the same ID element as the current line." (let ((inhibit-read-only t) - (entries (if (functionp 'tabulated-list-entries) + (entries (if (functionp tabulated-list-entries) (funcall tabulated-list-entries) tabulated-list-entries)) entry-id saved-pt saved-col) @@ -246,7 +246,7 @@ to the entry with the same ID element as the current line." (setq entries (sort entries sorter)) (if (cdr tabulated-list-sort-key) (setq entries (nreverse entries))) - (unless (functionp 'tabulated-list-entries) + (unless (functionp tabulated-list-entries) (setq tabulated-list-entries entries))))) ;; Print the resulting list. (dolist (elt entries) diff --git a/lisp/net/network-stream.el b/lisp/net/network-stream.el index 7a3d47ef1d1..81d05eabc5a 100644 --- a/lisp/net/network-stream.el +++ b/lisp/net/network-stream.el @@ -125,9 +125,8 @@ values: certificate. This parameter will only be used when doing TLS or STARTTLS connections. -If :use-starttls-if-possible is non-nil, do opportunistic -STARTTLS upgrades even if Emacs doesn't have built-in TLS -functionality. +:use-starttls-if-possible is a boolean that says to do opportunistic +STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality. :nowait is a boolean that says the connection should be made asynchronously, if possible." diff --git a/lisp/progmodes/cc-cmds.el b/lisp/progmodes/cc-cmds.el index 55ab6c9981c..9cf20ccb516 100644 --- a/lisp/progmodes/cc-cmds.el +++ b/lisp/progmodes/cc-cmds.el @@ -679,7 +679,7 @@ settings of `c-cleanup-list' are done." ;; We want to inhibit blinking the paren since this would be ;; most disruptive. We'll blink it ourselves later on. (old-blink-paren blink-paren-function) - blink-paren-function) + blink-paren-function case-fold-search) (c-save-buffer-state () (setq safepos (c-safe-position (point) (c-parse-state)) @@ -1086,7 +1086,7 @@ numeric argument is supplied, or the point is inside a literal." (interactive "*P") (let ((c-echo-syntactic-information-p nil) - final-pos close-paren-inserted found-delim) + final-pos close-paren-inserted found-delim case-fold-search) (self-insert-command (prefix-numeric-value arg)) (setq final-pos (point)) @@ -1172,7 +1172,8 @@ newline cleanups are done if appropriate; see the variable `c-cleanup-list'." (interactive "*P") (let ((literal (c-save-buffer-state () (c-in-literal))) ;; shut this up - (c-echo-syntactic-information-p nil)) + (c-echo-syntactic-information-p nil) + case-fold-search) (self-insert-command (prefix-numeric-value arg)) (if (and (not arg) (not literal)) @@ -1585,7 +1586,7 @@ defun." ; structure with other users of c-state-cache. (orig-point-min (point-min)) (orig-point-max (point-max)) lim ; Position of { which has been widened to. - where pos) + where pos case-fold-search) (save-restriction (if (eq c-defun-tactic 'go-outward) @@ -1709,7 +1710,8 @@ the open-parenthesis that starts a defun; see `beginning-of-defun'." ; structure with other users of c-state-cache. (orig-point-min (point-min)) (orig-point-max (point-max)) lim - where pos) + where pos case-fold-search) + (save-restriction (if (eq c-defun-tactic 'go-outward) (setq lim (c-widen-to-enclosing-decl-scope ; e.g. class, namespace @@ -1769,8 +1771,8 @@ with a brace block." (interactive) (c-save-buffer-state (beginning-of-defun-function end-of-defun-function - where pos name-end) - + where pos name-end case-fold-search) + (save-restriction (widen) (save-excursion @@ -1969,7 +1971,7 @@ As opposed to \\[c-beginning-of-defun] and \\[c-end-of-defun], this function does not require the declaration to contain a brace block." (interactive) - (let (decl-limits) + (let (decl-limits case-fold-search) (c-save-buffer-state nil ;; We try to be line oriented, unless there are several ;; declarations on the same line. @@ -2001,11 +2003,12 @@ function does not require the declaration to contain a brace block." (defun c-cpp-define-name () "Return the name of the current CPP macro, or NIL if we're not in one." (interactive) - (save-excursion - (and c-opt-cpp-macro-define-start - (c-beginning-of-macro) - (looking-at c-opt-cpp-macro-define-start) - (match-string-no-properties 1)))) + (let (case-fold-search) + (save-excursion + (and c-opt-cpp-macro-define-start + (c-beginning-of-macro) + (looking-at c-opt-cpp-macro-define-start) + (match-string-no-properties 1))))) ;; Movement by statements. @@ -2888,7 +2891,8 @@ See `c-indent-comment-alist' for a description." (eq (match-end 0) eot)) 'cpp-end-block) (t - 'other)))) + 'other))) + case-fold-search) (if (and (memq line-type '(anchored-comment empty-line)) c-indent-comments-syntactically-p) (let ((c-syntactic-context (c-guess-basic-syntax))) @@ -3024,7 +3028,7 @@ are treated as conditional clause limits. Normally they are ignored." (let* ((forward (> count 0)) (increment (if forward -1 1)) (search-function (if forward 're-search-forward 're-search-backward)) - new) + new case-fold-search) (unless (integerp target-depth) (setq target-depth (if target-depth -1 0))) (save-excursion @@ -3226,7 +3230,7 @@ balanced expression is found." In the macro case this also has the effect of realigning any line continuation backslashes, unless `c-auto-align-backslashes' is nil." (interactive "*") - (let ((here (point-marker)) decl-limits) + (let ((here (point-marker)) decl-limits case-fold-search) (unwind-protect (progn (c-save-buffer-state nil @@ -4638,7 +4642,8 @@ inside a preprocessor directive." (interactive "*") (let* (c-lit-limits c-lit-type - (c-macro-start c-macro-start)) + (c-macro-start c-macro-start) + case-fold-search) (c-save-buffer-state () (setq c-lit-limits (c-literal-limits nil nil t) diff --git a/lisp/progmodes/cc-mode.el b/lisp/progmodes/cc-mode.el index 7c018feefbb..ff18f56bbe8 100644 --- a/lisp/progmodes/cc-mode.el +++ b/lisp/progmodes/cc-mode.el @@ -1170,10 +1170,10 @@ Note that the style variables are always made local to the buffer." ;; ;; ;; void myfunc(T* p) {} - ;; + ;; ;; Type a space in the first blank line, and the fontification of the next ;; line was fouled up by context fontification. - (let ((new-beg beg) (new-end end) new-region) + (let ((new-beg beg) (new-end end) new-region case-fold-search) (if c-in-after-change-fontification (setq c-in-after-change-fontification nil) (save-restriction diff --git a/lisp/progmodes/gdb-mi.el b/lisp/progmodes/gdb-mi.el index 497d2440cfd..1be74ff544b 100644 --- a/lisp/progmodes/gdb-mi.el +++ b/lisp/progmodes/gdb-mi.el @@ -375,9 +375,8 @@ Emacs always switches to the thread which caused the stop." :version "23.2" :link '(info-link "(gdb)GDB/MI Async Records")) -(defcustom gdb-stopped-hooks nil - "This variable holds a list of functions to be called whenever -GDB stops. +(defcustom gdb-stopped-functions nil + "List of functions called whenever GDB stops. Each function takes one argument, a parsed MI response, which contains fields of corresponding MI *stopped async record: @@ -818,6 +817,8 @@ detailed description of this mode. nil 'local) (local-set-key "\C-i" 'completion-at-point) + (local-set-key [remap comint-delchar-or-maybe-eof] 'gdb-delchar-or-quit) + (setq gdb-first-prompt t) (setq gud-running nil) @@ -859,15 +860,8 @@ detailed description of this mode. (gdb-get-buffer-create 'gdb-inferior-io) (gdb-clear-inferior-io) - (set-process-filter (get-process "gdb-inferior") 'gdb-inferior-filter) - (gdb-input - ;; Needs GDB 6.4 onwards - (concat "-inferior-tty-set " - (or - ;; The process can run on a remote host. - (process-get (get-process "gdb-inferior") 'remote-tty) - (process-tty-name (get-process "gdb-inferior")))) - 'ignore) + (gdb-inferior-io--init-proc (get-process "gdb-inferior")) + (if (eq window-system 'w32) (gdb-input "-gdb-set new-console off" 'ignore)) (gdb-input "-gdb-set height 0" 'ignore) @@ -905,6 +899,25 @@ detailed description of this mode. (setq gdb-non-stop nil) (gdb-input "-gdb-set non-stop 0" 'ignore))) +(defun gdb-delchar-or-quit (arg) + "Delete ARG characters or send a quit command to GDB. +Send a quit only if point is at the end of the buffer, there is +no input, and GDB is waiting for input." + (interactive "p") + (unless (and (eq (current-buffer) gud-comint-buffer) + (eq gud-minor-mode 'gdbmi)) + (error "Not in a GDB-MI buffer")) + (let ((proc (get-buffer-process gud-comint-buffer))) + (if (and (eobp) proc (process-live-p proc) + (not gud-running) + (= (point) (marker-position (process-mark proc)))) + ;; Sending an EOF does not work with GDB-MI; submit an + ;; explicit quit command. + (progn + (insert "quit") + (comint-send-input t t)) + (delete-char arg)))) + (defvar gdb-define-alist nil "Alist of #define directives for GUD tooltips.") (defun gdb-create-define-alist () @@ -929,7 +942,6 @@ detailed description of this mode. (push (cons name define) gdb-define-alist)))) (declare-function tooltip-show "tooltip" (text &optional use-echo-area)) -(defvar tooltip-use-echo-area) (defun gdb-tooltip-print (expr) (with-current-buffer (gdb-get-buffer 'gdb-partial-output-buffer) @@ -937,7 +949,7 @@ detailed description of this mode. (if (re-search-forward ".*value=\\(\".*\"\\)" nil t) (tooltip-show (concat expr " = " (read (match-string 1))) - (or gud-tooltip-echo-area tooltip-use-echo-area + (or gud-tooltip-echo-area (not (display-graphic-p))))))) ;; If expr is a macro for a function don't print because of possible dangerous @@ -1510,6 +1522,31 @@ DOC is an optional documentation string." (gdb-display-buffer (gdb-get-buffer-create 'gdb-inferior-io) t)) +(defun gdb-inferior-io--init-proc (proc) + ;; Set up inferior I/O. Needs GDB 6.4 onwards. + (set-process-filter proc 'gdb-inferior-filter) + (set-process-sentinel proc 'gdb-inferior-io-sentinel) + (gdb-input + (concat "-inferior-tty-set " + ;; The process can run on a remote host. + (or (process-get proc 'remote-tty) + (process-tty-name proc))) + 'ignore)) + +(defun gdb-inferior-io-sentinel (proc str) + (when (eq (process-status proc) 'failed) + ;; When the debugged process exits, Emacs gets an EIO error on + ;; read from the pty, and stops listening to it. If the gdb + ;; process is still running, remove the pty, make a new one, and + ;; pass it to gdb. + (let ((gdb-proc (get-buffer-process gud-comint-buffer)) + (io-buffer (process-buffer proc))) + (when (and gdb-proc (process-live-p gdb-proc) + (buffer-live-p io-buffer)) + ;; `comint-exec' deletes the original process as a side effect. + (comint-exec io-buffer "gdb-inferior" nil nil nil) + (gdb-inferior-io--init-proc (get-buffer-process io-buffer)))))) + (defconst gdb-frame-parameters '((height . 14) (width . 80) (unsplittable . t) @@ -1746,24 +1783,27 @@ If `gdb-thread-number' is nil, just wrap NAME in asterisks." (setq gdb-output-sink 'user) (setq gdb-pending-triggers nil)) -(defun gdb-update () - "Update buffers showing status of debug session." +(defun gdb-update (&optional no-proc) + "Update buffers showing status of debug session. +If NO-PROC is non-nil, do not try to contact the GDB process." (when gdb-first-prompt (gdb-force-mode-line-update (propertize "initializing..." 'face font-lock-variable-name-face)) (gdb-init-1) (setq gdb-first-prompt nil)) - (gdb-get-main-selected-frame) + (unless no-proc + (gdb-get-main-selected-frame)) + ;; We may need to update gdb-threads-list so we can use (gdb-get-buffer-create 'gdb-threads-buffer) ;; gdb-break-list is maintained in breakpoints handler (gdb-get-buffer-create 'gdb-breakpoints-buffer) - (gdb-emit-signal gdb-buf-publisher 'update) + (unless no-proc + (gdb-emit-signal gdb-buf-publisher 'update)) (gdb-get-changed-registers) - (when (and (boundp 'speedbar-frame) (frame-live-p speedbar-frame)) (dolist (var gdb-var-list) (setcar (nthcdr 5 var) nil)) @@ -2045,7 +2085,7 @@ current thread and update GDB buffers." ;; In all-stop this updates gud-running properly as well. (gdb-update) (setq gdb-first-done-or-error nil)) - (run-hook-with-args 'gdb-stopped-hooks result))) + (run-hook-with-args 'gdb-stopped-functions result))) ;; Remove the trimmings from log stream containing debugging messages ;; being produced by GDB's internals, use warning face and send to GUD @@ -2085,23 +2125,28 @@ current thread and update GDB buffers." (setq gdb-output-sink 'emacs)) (gdb-clear-partial-output) - (when gdb-first-done-or-error - (unless (or token-number gud-running) - (setq gdb-filter-output (concat gdb-filter-output gdb-prompt-name))) - (gdb-update) - (setq gdb-first-done-or-error nil)) - (setq gdb-filter-output - (gdb-concat-output gdb-filter-output output-field)) + ;; The process may already be dead (e.g. C-d at the gdb prompt). + (let* ((proc (get-buffer-process gud-comint-buffer)) + (no-proc (or (null proc) + (memq (process-status proc) '(exit signal))))) - (if token-number - (progn - (with-current-buffer - (gdb-get-buffer-create 'gdb-partial-output-buffer) - (funcall - (cdr (assoc (string-to-number token-number) gdb-handler-alist)))) - (setq gdb-handler-alist - (assq-delete-all token-number gdb-handler-alist))))) + (when gdb-first-done-or-error + (unless (or token-number gud-running no-proc) + (setq gdb-filter-output (concat gdb-filter-output gdb-prompt-name))) + (gdb-update no-proc) + (setq gdb-first-done-or-error nil)) + + (setq gdb-filter-output + (gdb-concat-output gdb-filter-output output-field)) + + (when token-number + (with-current-buffer + (gdb-get-buffer-create 'gdb-partial-output-buffer) + (funcall + (cdr (assoc (string-to-number token-number) gdb-handler-alist)))) + (setq gdb-handler-alist + (assq-delete-all token-number gdb-handler-alist))))) (defun gdb-concat-output (so-far new) (cond @@ -4105,9 +4150,15 @@ This arrangement depends on the value of `gdb-many-windows'." (gud-find-file gdb-main-file))) (setq gdb-source-window win))))) +;; Called from `gud-sentinel' in gud.el: (defun gdb-reset () "Exit a debugging session cleanly. Kills the gdb buffers, and resets variables and the source buffers." + ;; The gdb-inferior buffer has a pty hooked up to the main gdb + ;; process. This pty must be deleted explicitly. + (let ((pty (get-process "gdb-inferior"))) + (if pty (delete-process pty))) + ;; Find gdb-mi buffers and kill them. (dolist (buffer (buffer-list)) (unless (eq buffer gud-comint-buffer) (with-current-buffer buffer diff --git a/lisp/progmodes/grep.el b/lisp/progmodes/grep.el index 569e864a1c6..a6ae42f86b1 100644 --- a/lisp/progmodes/grep.el +++ b/lisp/progmodes/grep.el @@ -728,9 +728,9 @@ This function is called from `compilation-filter-hook'." (defun grep (command-args) "Run grep, with user-specified args, and collect output in a buffer. While grep runs asynchronously, you can use \\[next-error] (M-x next-error), -or \\<grep-mode-map>\\[compile-goto-error] in the grep \ -output buffer, to go to the lines where grep -found matches. +or \\<grep-mode-map>\\[compile-goto-error] in the *grep* \ +buffer, to go to the lines where grep found +matches. To kill the grep job before it finishes, type \\[kill-compilation]. For doing a recursive `grep', see the `rgrep' command. For running `grep' in a specific directory, see `lgrep'. @@ -957,10 +957,11 @@ With \\[universal-argument] prefix, you can edit the constructed shell command l before it is executed. With two \\[universal-argument] prefixes, directly edit and run `grep-find-command'. -Collect output in a buffer. While find runs asynchronously, you -can use \\[next-error] (M-x next-error), or \\<grep-mode-map>\\[compile-goto-error] \ +Collect output in a buffer. While the recursive grep is running, +you can use \\[next-error] (M-x next-error), or \\<grep-mode-map>\\[compile-goto-error] \ in the grep output buffer, -to go to the lines where grep found matches. +to visit the lines where matches were found. To kill the job +before it finishes, type \\[kill-compilation]. This command shares argument histories with \\[lgrep] and \\[grep-find]. diff --git a/lisp/server.el b/lisp/server.el index c82a639eadf..123fea3743a 100644 --- a/lisp/server.el +++ b/lisp/server.el @@ -1174,6 +1174,13 @@ The following commands are accepted by the client: ;; Unknown command. (arg (error "Unknown command: %s" arg)))) + ;; If both -no-wait and -tty are given with file or sexp + ;; arguments, use an existing frame. + (and nowait + (not (eq tty-name 'window-system)) + (or files commands) + (setq use-current-frame t)) + (setq frame (cond ((and use-current-frame diff --git a/lisp/subr.el b/lisp/subr.el index ff93cd22210..8e296aa7422 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -1888,8 +1888,7 @@ Used from `delayed-warnings-hook' (which see)." (push warning collapsed))) (setq delayed-warnings-list (nreverse collapsed)))) -;; At present this is only really useful for Emacs internals. -;; Document in the lispref if it becomes generally useful. +;; At present this is only used for Emacs internals. ;; Ref http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00085.html (defvar delayed-warnings-hook '(collapse-delayed-warnings display-delayed-warnings) @@ -2308,6 +2307,8 @@ is nil and `use-dialog-box' is non-nil." (discard-input)))) (let ((ret (eq answer 'act))) (unless noninteractive + ;; FIXME this prints one too many spaces, since prompt + ;; already ends in a space. Eg "... (y or n) y". (message "%s %s" prompt (if ret "y" "n"))) ret))) diff --git a/lisp/window.el b/lisp/window.el index 934b6067d08..c148f5ee01f 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -514,17 +514,19 @@ window).") (if (window-valid-p ignore) (eq window ignore) ignore)) (defun window-min-size (&optional window horizontal ignore) - "Return the minimum number of lines of WINDOW. + "Return the minimum size of WINDOW. WINDOW can be an arbitrary window and defaults to the selected one. Optional argument HORIZONTAL non-nil means return the -minimum number of columns of WINDOW. +minimum number of columns of WINDOW; otherwise return the minimum +number of WINDOW's lines. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE, if non-nil, means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE equal `safe' means live +`window-min-width' settings. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines and -`window-safe-min-width' columns. IGNORE a window means ignore -restrictions for that window only." +`window-safe-min-width' columns. If IGNORE is a window, ignore +restrictions for that window only. Any other non-nil value +means ignore all of the above restrictions for all windows." (window--min-size-1 (window-normalize-window window) horizontal ignore)) @@ -614,12 +616,13 @@ columns. If WINDOW cannot be shrunk by -DELTA lines or columns, return the minimum value in the range DELTA..0 by which WINDOW can be shrunk. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE equal `safe' means live +`window-min-width' settings. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines and -`window-safe-min-width' columns. IGNORE any window means ignore -restrictions for that window only." +`window-safe-min-width' columns. If IGNORE is a window, ignore +restrictions for that window only. Any other non-nil value means +ignore all of the above restrictions for all windows." (setq window (window-normalize-window window)) (cond ((< delta 0) @@ -734,20 +737,21 @@ window. Return zero if WINDOW cannot be shrunk. Optional argument HORIZONTAL non-nil means return number of columns by which WINDOW can be shrunk. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE a window means ignore -restrictions for that window only. IGNORE equal `safe' means +`window-min-width' settings. If IGNORE is a window, ignore +restrictions for that window only. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines -and `window-safe-min-width' columns. +and `window-safe-min-width' columns. Any other non-nil value +means ignore all of the above restrictions for all windows. -Optional argument TRAIL `before' means only windows to the left -of or above WINDOW can be enlarged. Optional argument TRAIL -`after' means only windows to the right of or below WINDOW can be -enlarged. +Optional argument TRAIL restricts the windows that can be enlarged. +If its value is `before', only windows to the left of or above WINDOW +can be enlarged. If it is `after', only windows to the right of or +below WINDOW can be enlarged. Optional argument NOUP non-nil means don't go up in the window -tree but try to enlarge windows within WINDOW's combination only. +tree, but try to enlarge windows within WINDOW's combination only. Optional argument NODOWN non-nil means don't check whether WINDOW itself (and its child windows) can be shrunk; check only whether @@ -808,24 +812,25 @@ at least one other window can be enlarged appropriately." (window--max-delta-1 parent delta horizontal ignore trail)))))) (defun window-max-delta (&optional window horizontal ignore trail noup nodown) - "Return maximum number of lines WINDOW by which WINDOW can be enlarged. + "Return maximum number of lines by which WINDOW can be enlarged. WINDOW can be an arbitrary window and defaults to the selected window. The return value is zero if WINDOW cannot be enlarged. Optional argument HORIZONTAL non-nil means return maximum number of columns by which WINDOW can be enlarged. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE a window means ignore -restrictions for that window only. IGNORE equal `safe' means +`window-min-width' settings. If IGNORE is a window, ignore +restrictions for that window only. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines -and `window-safe-min-width' columns. +and `window-safe-min-width' columns. Any other non-nil value means +ignore all of the above restrictions for all windows. -Optional argument TRAIL `before' means only windows to the left -of or below WINDOW can be shrunk. Optional argument TRAIL -`after' means only windows to the right of or above WINDOW can be -shrunk. +Optional argument TRAIL restricts the windows that can be enlarged. +If its value is `before', only windows to the left of or above WINDOW +can be enlarged. If it is `after', only windows to the right of or +below WINDOW can be enlarged. Optional argument NOUP non-nil means don't go up in the window tree but try to obtain the entire space from windows within @@ -860,12 +865,13 @@ columns. If WINDOW cannot be shrunk by -DELTA lines or columns, return the minimum value in the range DELTA..0 that can be used for shrinking WINDOW. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE a window means ignore -restrictions for that window only. IGNORE equal `safe' means +`window-min-width' settings. If IGNORE is a window, ignore +restrictions for that window only. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines -and `window-safe-min-width' columns. +and `window-safe-min-width' columns. Any other non-nil value +means ignore all of the above restrictions for all windows. Optional argument TRAIL `before' means only windows to the left of or below WINDOW can be shrunk. Optional argument TRAIL @@ -916,17 +922,18 @@ columns. If WINDOW cannot be shrunk by -DELTA lines or columns, return the minimum value in the range DELTA..0 that can be used for shrinking WINDOW. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE a window means ignore -restrictions for that window only. IGNORE equal `safe' means +`window-min-width' settings. If IGNORE is a window, ignore +restrictions for that window only. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines -and `window-safe-min-width' columns." +and `window-safe-min-width' columns. Any other non-nil value +means ignore all of the above restrictions for all windows." (setq window (window-normalize-window window)) (window--resizable window delta horizontal ignore)) (defun window-total-size (&optional window horizontal) - "Return the total height or width of window WINDOW. + "Return the total height or width of WINDOW. If WINDOW is omitted or nil, it defaults to the selected window. If HORIZONTAL is omitted or nil, return the total height of @@ -941,7 +948,7 @@ the total width, in columns, like `window-total-width'." ;; See discussion in bug#4543. (defun window-full-height-p (&optional window) - "Return t if WINDOW is as high as the containing frame. + "Return t if WINDOW is as high as its containing frame. More precisely, return t if and only if the total height of WINDOW equals the total height of the root window of WINDOW's frame. WINDOW can be any window and defaults to the selected @@ -951,7 +958,7 @@ one." (window-total-size (frame-root-window window)))) (defun window-full-width-p (&optional window) - "Return t if WINDOW is as wide as the containing frame. + "Return t if WINDOW is as wide as its containing frame. More precisely, return t if and only if the total width of WINDOW equals the total width of the root window of WINDOW's frame. WINDOW can be any window and defaults to the selected one." @@ -1115,7 +1122,7 @@ SIDE can be any of the symbols `left', `top', `right' or "Return window in DIRECTION as seen from WINDOW. DIRECTION must be one of `above', `below', `left' or `right'. WINDOW must be a live window and defaults to the selected one. -IGNORE, when non-nil means a window can be returned even if its +IGNORE non-nil means a window can be returned even if its `no-other-window' parameter is non-nil." (setq window (window-normalize-window window t)) (unless (memq direction '(above below left right)) @@ -1420,7 +1427,7 @@ windows." (defun window--resize-mini-window (window delta) "Resize minibuffer window WINDOW by DELTA lines. If WINDOW cannot be resized by DELTA lines make it as large (or -as small) as possible but don't signal an error." +as small) as possible, but don't signal an error." (when (window-minibuffer-p window) (let* ((frame (window-frame window)) (root (frame-root-window frame)) @@ -1461,12 +1468,13 @@ horizontally by DELTA columns. In this case a positive DELTA means enlarge WINDOW by DELTA columns. DELTA negative means WINDOW shall be shrunk by -DELTA columns. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE any window means ignore -restrictions for that window only. IGNORE equal `safe' means +`window-min-width' settings. If IGNORE is a window, ignore +restrictions for that window only. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines -and `window-safe-min-width' columns. +and `window-safe-min-width' columns. Any other non-nil value +means ignore all of the above restrictions for all windows. This function resizes other windows proportionally and never deletes any windows. If you want to move only the low (right) @@ -1516,9 +1524,9 @@ HORIZONTAL non-nil means set the new normal width of these windows. WINDOW specifies a child window of PARENT that has been resized by THIS-DELTA lines (columns). -Optional argument TRAIL either 'before or 'after means set values -for windows before or after WINDOW only. Optional argument -OTHER-DELTA a number specifies that this many lines (columns) +Optional argument TRAIL either `before' or `after' means set values +only for windows before or after WINDOW. Optional argument +OTHER-DELTA, a number, specifies that this many lines (columns) have been obtained from (or returned to) an ancestor window of PARENT in order to resize WINDOW." (let* ((delta-normal @@ -1618,12 +1626,13 @@ be a horizontally combined internal window. WINDOW, if specified, must denote a child window of PARENT that is resized by DELTA lines. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE equal `safe' means live +`window-min-width' settings. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines and -`window-safe-min-width' columns. IGNORE any window means ignore -restrictions for that window only. +`window-safe-min-width' columns. If IGNORE is a window, ignore +restrictions for that window only. Any other non-nil value means +ignore all of the above restrictions for all windows. Optional arguments TRAIL and EDGE, when non-nil, restrict the set of windows that shall be resized. If TRAIL equals `before', @@ -1790,12 +1799,13 @@ Optional argument HORIZONTAL non-nil means resize other windows when WINDOW is resized horizontally by DELTA columns. WINDOW itself is not resized by this function. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE equal `safe' means live +`window-min-width' settings. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines and -`window-safe-min-width' columns. IGNORE any window means ignore -restrictions for that window only. +`window-safe-min-width' columns. If IGNORE is a window, ignore +restrictions for that window only. Any other non-nil value means +ignore all of the above restrictions for all windows. Optional arguments TRAIL and EDGE, when non-nil, refine the set of windows that shall be resized. If TRAIL equals `before', @@ -1891,12 +1901,13 @@ preferably only resize windows adjacent to EDGE." Optional argument HORIZONTAL non-nil means resize WINDOW horizontally by DELTA columns. -Optional argument IGNORE non-nil means ignore any restrictions +Optional argument IGNORE non-nil means ignore restrictions imposed by fixed size windows, `window-min-height' or -`window-min-width' settings. IGNORE equal `safe' means live +`window-min-width' settings. If IGNORE equals `safe', live windows may get as small as `window-safe-min-height' lines and -`window-safe-min-width' columns. IGNORE any window means ignore -restrictions for that window only. +`window-safe-min-width' columns. If IGNORE is a window, ignore +restrictions for that window only. Any other non-nil value +means ignore all of the above restrictions for all windows. Optional argument ADD non-nil means add DELTA to the new total size of WINDOW. @@ -1986,7 +1997,7 @@ any windows." Optional argument HORIZONTAL non-nil means move WINDOW's right edge by DELTA columns. WINDOW defaults to the selected window. -If DELTA is greater zero, then move the edge downwards or to the +If DELTA is greater than zero, move the edge downwards or to the right. If DELTA is less than zero, move the edge upwards or to the left. If the edge can't be moved by DELTA lines or columns, move it as far as possible in the desired direction." @@ -2091,7 +2102,7 @@ move it as far as possible in the desired direction." (error "Failed adjusting window %s" window))))))) (defun enlarge-window (delta &optional horizontal) - "Make selected window DELTA lines taller. + "Make the selected window DELTA lines taller. Interactively, if no argument is given, make the selected window one line taller. If optional argument HORIZONTAL is non-nil, make selected window wider by DELTA columns. If DELTA is @@ -2112,7 +2123,7 @@ Return nil." horizontal)))) (defun shrink-window (delta &optional horizontal) - "Make selected window DELTA lines smaller. + "Make the selected window DELTA lines smaller. Interactively, if no argument is given, make the selected window one line smaller. If optional argument HORIZONTAL is non-nil, make selected window narrower by DELTA columns. If DELTA is diff --git a/src/ChangeLog b/src/ChangeLog index ae91f04635b..fa6c47bf955 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,30 @@ +2012-04-20 Chong Yidong <cyd@gnu.org> + + * process.c (wait_reading_process_output): If EIO occurs on a pty, + set the status to "failed" and ensure that sentinel is run. + +2012-04-20 Glenn Morris <rgm@gnu.org> + + * process.c (Fset_process_inherit_coding_system_flag) + (Fset_process_query_on_exit_flag): Doc fix (mention return value). + (Fmake_network_process, Fmake_serial_process): Doc fix. + +2012-04-20 Eli Zaretskii <eliz@gnu.org> + + * xdisp.c (string_buffer_position_lim): Limit starting position to + BEGV. + (set_cursor_from_row): If called for a mode-line or header-line + row, return zero immediately. + (try_cursor_movement): If inside continuation line, don't back up + farther than the first row after the header line, if any. Don't + consider the header-line row as "partially visible", even if + MATRIX_ROW_PARTIALLY_VISIBLE_P returns non-zero. (Bug#11261) + +2012-04-20 Atsuo Ohki <ohki@gssm.otsuka.tsukuba.ac.jp> (tiny change) + + * lread.c (lisp_file_lexically_bound_p): Fix hang at ";-*-\n" (bug#11238). + +2012-04-20 Teodor Zlatanov <tzz@lifelogs.com> 2012-04-18 Paul Eggert <eggert@cs.ucla.edu> configure: new option --enable-gcc-warnings (Bug#11207) diff --git a/src/process.c b/src/process.c index 2609a9cc250..cf6d40052a7 100644 --- a/src/process.c +++ b/src/process.c @@ -1077,7 +1077,9 @@ is more appropriate for saving the process buffer. Binding the variable `inherit-process-coding-system' to non-nil before starting the process is an alternative way of setting the inherit flag -for the process which will run. */) +for the process which will run. + +This function returns FLAG. */) (register Lisp_Object process, Lisp_Object flag) { CHECK_PROCESS (process); @@ -1090,7 +1092,8 @@ DEFUN ("set-process-query-on-exit-flag", 2, 2, 0, doc: /* Specify if query is needed for PROCESS when Emacs is exited. If the second argument FLAG is non-nil, Emacs will query the user before -exiting or killing a buffer if PROCESS is running. */) +exiting or killing a buffer if PROCESS is running. This function +returns FLAG. */) (register Lisp_Object process, Lisp_Object flag) { CHECK_PROCESS (process); @@ -2532,7 +2535,7 @@ could be "COM1", or "\\\\.\\COM10" for ports higher than COM9 (double the backslashes in strings). :speed SPEED -- (mandatory) is handled by `serial-process-configure', -which is called by `make-serial-process'. +which this function calls. :name NAME -- NAME is the name of the process. If NAME is not given, the value of PORT is used. @@ -2561,13 +2564,12 @@ but you can send outgoing data. The stopped state is cleared by :plist PLIST -- Install PLIST as the initial plist of the process. -:speed :bytesize :parity :stopbits :flowcontrol --- These arguments are handled by `serial-process-configure', which is -called by `make-serial-process'. +-- This function calls `serial-process-configure' to handle these +arguments. The original argument list, possibly modified by later configuration, is available via the function `process-contact'. @@ -2801,7 +2803,7 @@ The stopped state is cleared by `continue-process' and set by :filter-multibyte BOOL -- If BOOL is non-nil, strings given to the process filter are multibyte, otherwise they are unibyte. If this keyword is not specified, the strings are multibyte if -`default-enable-multibyte-characters' is non-nil. +the default value of `enable-multibyte-characters' is non-nil. :sentinel SENTINEL -- Install SENTINEL as the process sentinel. @@ -4898,16 +4900,23 @@ wait_reading_process_output (int time_limit, int microsecs, int read_kbd, It can't hurt. */ else if (nread == -1 && errno == EIO) { - /* Don't do anything if only a pty, with no associated - process (bug#10933). */ - if (XPROCESS (proc)->pid != -2) { - /* Clear the descriptor now, so we only raise the signal - once. */ - FD_CLR (channel, &input_wait_mask); - FD_CLR (channel, &non_keyboard_wait_mask); - - kill (getpid (), SIGCHLD); - } + struct Lisp_Process *p = XPROCESS (proc); + + /* Clear the descriptor now, so we only raise the + signal once. */ + FD_CLR (channel, &input_wait_mask); + FD_CLR (channel, &non_keyboard_wait_mask); + + if (p->pid == -2) + { + /* If the EIO occurs on a pty, sigchld_handler's + wait3() will not find the process object to + delete. Do it here. */ + p->tick = ++process_tick; + p->status = Qfailed; + } + else + kill (getpid (), SIGCHLD); } #endif /* HAVE_PTYS */ /* If we can detect process termination, don't consider the diff --git a/src/xdisp.c b/src/xdisp.c index ea964f4dadc..3cbd4b172f4 100644 --- a/src/xdisp.c +++ b/src/xdisp.c @@ -4979,7 +4979,7 @@ string_buffer_position_lim (Lisp_Object string, Lisp_Object limit, prop, pos; int found = 0; - pos = make_number (from); + pos = make_number (max (from, BEGV)); if (!back_p) /* looking forward */ { @@ -13690,6 +13690,13 @@ set_cursor_from_row (struct window *w, struct glyph_row *row, comes from a text property, not from an overlay. */ int string_from_text_prop = 0; + /* Don't even try doing anything if called for a mode-line or + header-line row, since the rest of the code isn't prepared to + deal with such calamities. */ + xassert (!row->mode_line_p); + if (row->mode_line_p) + return 0; + /* Skip over glyphs not having an object at the start and the end of the row. These are special glyphs like truncation marks on terminal frames. */ @@ -14910,6 +14917,8 @@ try_cursor_movement (Lisp_Object window, struct text_pos startp, int *scroll_ste else if (rc != CURSOR_MOVEMENT_SUCCESS && !NILP (BVAR (XBUFFER (w->buffer), bidi_display_reordering))) { + struct glyph_row *row1; + /* If rows are bidi-reordered and point moved, back up until we find a row that does not belong to a continuation line. This is because we must consider @@ -14920,24 +14929,28 @@ try_cursor_movement (Lisp_Object window, struct text_pos startp, int *scroll_ste /* FIXME: Revisit this when glyph ``spilling'' in continuation lines' rows is implemented for bidi-reordered rows. */ - while (MATRIX_ROW_CONTINUATION_LINE_P (row)) + for (row1 = MATRIX_FIRST_TEXT_ROW (w->current_matrix); + MATRIX_ROW_CONTINUATION_LINE_P (row); + --row) { /* If we hit the beginning of the displayed portion without finding the first row of a continued line, give up. */ - if (row <= w->current_matrix->rows) + if (row <= row1) { rc = CURSOR_MOVEMENT_MUST_SCROLL; break; } xassert (row->enabled_p); - --row; } } if (must_scroll) ; else if (rc != CURSOR_MOVEMENT_SUCCESS && MATRIX_ROW_PARTIALLY_VISIBLE_P (w, row) + /* Make sure this isn't a header line by any chance, since + then MATRIX_ROW_PARTIALLY_VISIBLE_P might yield non-zero. */ + && !row->mode_line_p && make_cursor_line_fully_visible_p) { if (PT == MATRIX_ROW_END_CHARPOS (row) |