[Emacs-diffs] trunk r116505: Some doc updates for default process sentinels and filters not being nil

[Glenn Morris]

------------------------------------------------------------
revno: 116505
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Fri 2014-02-21 00:04:15 -0800
message:
  Some doc updates for default process sentinels and filters not being nil
  
  * doc/lispref/internals.texi (Process Internals):
  * doc/lispref/processes.texi (Deleting Processes, Output from Processes)
  (Process Buffers, Filter Functions, Accepting Output, Sentinels)
  (Network, Network Servers, Network Processes, Serial Ports):
  Filters and sentinels can no longer be nil.
  
  * doc/lispref/elisp.texi (Top): Menu update.
  
  * doc/misc/flymake.texi (Starting the syntax check process): Grammar fix.
  
  * doc/misc/tramp.texi (External packages): Grammar fix.
  Reword for default sentinel not being nil any more.
  
  * src/process.c (Fprocess_buffer, Faccept_process_output)
  (Finternal_default_process_filter, Finternal_default_process_sentinel):
  Doc fixes.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/elisp.texi         elisp.texi-20091113204419-o5vbwnq5f7feedwu-6176
  doc/lispref/internals.texi     
internals.texi-20091113204419-o5vbwnq5f7feedwu-6188
  doc/lispref/processes.texi     
processes.texi-20091113204419-o5vbwnq5f7feedwu-6207
  doc/misc/ChangeLog             changelog-20091113204419-o5vbwnq5f7feedwu-6331
  doc/misc/flymake.texi          
flymake.texi-20091113204419-o5vbwnq5f7feedwu-6302
  doc/misc/tramp.texi            tramp.texi-20091113204419-o5vbwnq5f7feedwu-6324
  src/ChangeLog                  changelog-20091113204419-o5vbwnq5f7feedwu-1438
  src/process.c                  process.c-20091113204419-o5vbwnq5f7feedwu-462

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-02-20 07:38:47 +0000
+++ b/doc/lispref/ChangeLog     2014-02-21 08:04:15 +0000
@@ -1,3 +1,12 @@
+2014-02-21  Glenn Morris  <address@hidden>
+
+       * internals.texi (Process Internals):
+       * processes.texi (Deleting Processes, Output from Processes)
+       (Process Buffers, Filter Functions, Accepting Output, Sentinels)
+       (Network, Network Servers, Network Processes, Serial Ports):
+       Filters and sentinels can no longer be nil.
+       * elisp.texi (Top): Menu update.
+
 2014-02-20  Glenn Morris  <address@hidden>
 
        * functions.texi (Defining Functions): Mention defalias-fset-function.

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2014-01-10 19:40:32 +0000
+++ b/doc/lispref/elisp.texi    2014-02-21 08:04:15 +0000
@@ -1305,7 +1305,7 @@
 
 Receiving Output from Processes
 
-* Process Buffers::         If no filter, output is put in a buffer.
+* Process Buffers::         By default, output is put in a buffer.
 * Filter Functions::        Filter functions accept output from the process.
 * Decoding Output::         Filters can get unibyte or multibyte strings.
 * Accepting Output::        How to wait until process output arrives.

=== modified file 'doc/lispref/internals.texi'
--- a/doc/lispref/internals.texi        2014-01-01 07:43:34 +0000
+++ b/doc/lispref/internals.texi        2014-02-21 08:04:15 +0000
@@ -1469,12 +1469,10 @@
 process is running or @code{t} if the process is stopped.
 
 @item filter
-If address@hidden, a function used to accept output from the process
-instead of a buffer.
+A function used to accept output from the process.
 
 @item sentinel
-If address@hidden, a function called whenever the state of the process
-changes.
+A function called whenever the state of the process changes.
 
 @item buffer
 The associated buffer of the process.

=== modified file 'doc/lispref/processes.texi'
--- a/doc/lispref/processes.texi        2014-01-01 07:43:34 +0000
+++ b/doc/lispref/processes.texi        2014-02-21 08:04:15 +0000
@@ -696,7 +696,7 @@
 at any time.  If you explicitly delete a terminated process before it
 is deleted automatically, no harm results.  Deleting a running
 process sends a signal to terminate it (and its child processes, if
-any), and calls the process sentinel if it has one.  @xref{Sentinels}.
+any), and calls the process sentinel.  @xref{Sentinels}.
 
   When a process is deleted, the process object itself continues to
 exist as long as other Lisp objects point to it.  All the Lisp
@@ -719,7 +719,7 @@
 buffer, or the name of a buffer.  (A buffer or buffer-name stands for
 the process that @code{get-buffer-process} returns.)  Calling
 @code{delete-process} on a running process terminates it, updates the
-process status, and runs the sentinel (if any) immediately.  If the
+process status, and runs the sentinel immediately.  If the
 process has already terminated, calling @code{delete-process} has no
 effect on its status, or on the running of its sentinel (which will
 happen sooner or later).
@@ -1170,7 +1170,7 @@
 shell command.
 
 @menu
-* Process Buffers::         If no filter, output is put in a buffer.
+* Process Buffers::         By default, output is put in a buffer.
 * Filter Functions::        Filter functions accept output from the process.
 * Decoding Output::         Filters can get unibyte or multibyte strings.
 * Accepting Output::        How to wait until process output arrives.
@@ -1187,11 +1187,12 @@
 Many applications of processes also use the buffer for editing input to
 be sent to the process, but this is not built into Emacs Lisp.
 
-  Unless the process has a filter function (@pxref{Filter Functions}),
-its output is inserted in the associated buffer.  The position to insert
-the output is determined by the @code{process-mark}, which is then
-updated to point to the end of the text just inserted.  Usually, but not
-always, the @code{process-mark} is at the end of the buffer.
+  By default, process output is inserted in the associated buffer.
+(You can change this by defining a custom filter function,
address@hidden Functions}).  The position to insert the output is
+determined by the @code{process-mark}, which is then updated to point
+to the end of the text just inserted.  Usually, but not always, the
address@hidden is at the end of the buffer.
 
 @findex process-kill-buffer-query-function
   Killing the associated buffer of a process also kills the process.
@@ -1268,10 +1269,9 @@
 @cindex process filter
 
   A process @dfn{filter function} is a function that receives the
-standard output from the associated process.  If a process has a filter,
-then @emph{all} output from that process is passed to the filter.  The
-process buffer is used directly for output from the process only when
-there is no filter.
+standard output from the associated process.  @emph{all} output from
+that process is passed to the filter.  The default filter simply
+outputs directly to the process buffer.
 
   The filter function can only be called when Emacs is waiting for
 something, because process output arrives only at such times.  Emacs
@@ -1300,8 +1300,8 @@
 filter function.  @xref{Debugger}.
 
   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 make sure that they save the
+process's buffer, mimicking the actions of the default 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
@@ -1357,12 +1357,12 @@
 
 @defun set-process-filter process filter
 This function gives @var{process} the filter function @var{filter}.  If
address@hidden is @code{nil}, it gives the process no filter.
address@hidden is @code{nil}, it gives the process the default filter,
+which inserts the process output into the process buffer.
 @end defun
 
 @defun process-filter process
-This function returns the filter function of @var{process}, or @code{nil}
-if it has none.
+This function returns the filter function of @var{process}.
 @end defun
 
   Here is an example of the use of a filter function:
@@ -1401,8 +1401,7 @@
 
 @ignore   @c The code in this example doesn't show the right way to do things.
 Here is another, more realistic example, which demonstrates how to use
-the process mark to do insertion in the same fashion as is done when
-there is no filter function:
+the process mark to do insertion in the same fashion as the default filter:
 
 @smallexample
 @group
@@ -1474,9 +1473,9 @@
 
 @defun accept-process-output &optional process seconds millisec just-this-one
 This function allows Emacs to read pending output from processes.  The
-output is inserted in the associated buffers or given to their filter
-functions.  If @var{process} is address@hidden then this function does
-not return until some output has been received from @var{process}.
+output is given to their filter functions.  If @var{process} is
address@hidden then this function does not return until some output
+has been received from @var{process}.
 
 The arguments @var{seconds} and @var{millisec} let you specify timeout
 periods.  The former specifies a period measured in seconds and the
@@ -1591,9 +1590,9 @@
 
 @defun set-process-sentinel process sentinel
 This function associates @var{sentinel} with @var{process}.  If
address@hidden is @code{nil}, then the process will have no sentinel.
-The default behavior when there is no sentinel is to insert a message in
-the process's buffer when the process status changes.
address@hidden is @code{nil}, then the process will have the default
+sentinel, which inserts a message in the process's buffer when the
+process status changes.
 
 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
@@ -1616,8 +1615,7 @@
 @end defun
 
 @defun process-sentinel process
-This function returns the sentinel of @var{process}, or @code{nil} if it
-has none.
+This function returns the sentinel of @var{process}.
 @end defun
 
 @defun waiting-for-user-input-p
@@ -1974,7 +1972,7 @@
 
 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
+unless you specify your own filter function to handle the output.  If
 @var{buffer} is @code{nil}, it means that the connection is not
 associated with any buffer.
 
@@ -2082,7 +2080,7 @@
 is unique for each connection in the Emacs session.
 
 @item
-If the server's filter is address@hidden, the connection process does
+If the server has a non-default filter, the connection process does
 not get a separate process buffer; otherwise, Emacs creates a new
 buffer for the purpose.  The buffer name is the server's buffer name
 or process name, concatenated with the client identification string.
@@ -2284,7 +2282,8 @@
 @xref{Query Before Exit}.
 
 @item :filter @var{filter}
-Initialize the process filter to @var{filter}.
+Initialize the process filter to @var{filter}.  (Otherwise the default
+filter is used.)
 
 @item :filter-multibyte @var{multibyte}
 If @var{multibyte} is address@hidden, strings given to the process
@@ -2292,7 +2291,8 @@
 default value of @code{enable-multibyte-characters}.
 
 @item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.
+Initialize the process sentinel to @var{sentinel}.  (Otherwise the default
+sentinel is used.)
 
 @item :log @var{log}
 Initialize the log function of a server process to @var{log}.  The log
@@ -2580,10 +2580,12 @@
 @code{stop-process}.
 
 @item :filter @var{filter}
-Install @var{filter} as the process filter.
+Install @var{filter} as the process filter.  (Otherwise the default
+filter is used.)
 
 @item :sentinel @var{sentinel}
-Install @var{sentinel} as the process sentinel.
+Install @var{sentinel} as the process sentinel.  (Otherwise the default
+sentinel is used.)
 
 @item :plist @var{plist}
 Install @var{plist} as the initial plist of the process.

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2014-02-19 19:31:02 +0000
+++ b/doc/misc/ChangeLog        2014-02-21 08:04:15 +0000
@@ -1,3 +1,10 @@
+2014-02-21  Glenn Morris  <address@hidden>
+
+       * flymake.texi (Starting the syntax check process): Grammar fix.
+
+       * tramp.texi (External packages): Grammar fix.
+       Reword for default sentinel not being nil any more.
+
 2014-02-19  Michael Albinus  <address@hidden>
 
        * trampver.texi: Update release number.

=== modified file 'doc/misc/flymake.texi'
--- a/doc/misc/flymake.texi     2014-01-13 15:22:47 +0000
+++ b/doc/misc/flymake.texi     2014-02-21 08:04:15 +0000
@@ -695,8 +695,8 @@
 
 The command line (command name and the list of arguments) for launching a 
process is returned by the
 initialization function.  Flymake then just calls @code{start-process}
-to start an asynchronous process and configures process filter and
-sentinel which is used for processing the output of the syntax check
+to start an asynchronous process and configures a process filter and
+sentinel, which are used for processing the output of the syntax check
 tool.
 
 @node Parsing the output

=== modified file 'doc/misc/tramp.texi'
--- a/doc/misc/tramp.texi       2014-01-12 15:19:07 +0000
+++ b/doc/misc/tramp.texi       2014-02-21 08:04:15 +0000
@@ -3766,10 +3766,10 @@
 it has seen so far.
 
 This is a performance degradation, because the lost file attributes
-must be recomputed when needed again.  In cases the caller of
+must be recomputed when needed again.  In cases where the caller of
 @code{process-file} knows that there are no file attribute changes, it
-shall let-bind the variable @code{process-file-side-effects} to
address@hidden  @value{tramp} wouldn't flush the file attributes cache then.
+should let-bind the variable @code{process-file-side-effects} to
address@hidden  Then @value{tramp} won't flush the file attributes cache.
 
 @lisp
 (let (process-file-side-effects)
@@ -3779,8 +3779,8 @@
 For asynchronous processes, @value{tramp} flushes the file attributes
 cache via a process sentinel.  If the caller of
 @code{start-file-process} knows that there are no file attribute
-changes, it shall set the process sentinel to @code{nil}.  In case the
-caller defines an own process sentinel, @value{tramp}'s process
+changes, it should set the process sentinel to the default.  In cases
+where the caller defines its own process sentinel, @value{tramp}'s process
 sentinel is overwritten.  The caller can still flush the file
 attributes cache in its process sentinel with this code:
 

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2014-02-21 08:02:05 +0000
+++ b/src/ChangeLog     2014-02-21 08:04:15 +0000
@@ -1,3 +1,9 @@
+2014-02-21  Glenn Morris  <address@hidden>
+
+       * process.c (Fprocess_buffer, Faccept_process_output)
+       (Finternal_default_process_filter, Finternal_default_process_sentinel):
+       Doc fixes.
+
 2014-02-21  Martin Rudalics  <address@hidden>
 
        * window.c (Fwindow_scroll_bar_width): New function.

=== modified file 'src/process.c'
--- a/src/process.c     2014-01-30 17:22:30 +0000
+++ b/src/process.c     2014-02-21 08:04:15 +0000
@@ -1,7 +1,7 @@
 /* Asynchronous subprocess control for GNU Emacs.
 
-Copyright (C) 1985-1988, 1993-1996, 1998-1999, 2001-2014 Free Software
-Foundation, Inc.
+Copyright (C) 1985-1988, 1993-1996, 1998-1999, 2001-2014
+  Free Software Foundation, Inc.
 
 This file is part of GNU Emacs.
 
@@ -1022,7 +1022,7 @@
 DEFUN ("process-buffer", Fprocess_buffer, Sprocess_buffer,
        1, 1, 0,
        doc: /* Return the buffer PROCESS is associated with.
-Output from PROCESS is inserted in this buffer unless PROCESS has a filter.  
*/)
+The default process filter inserts output from PROCESS into this buffer.  */)
   (register Lisp_Object process)
 {
   CHECK_PROCESS (process);
@@ -1049,7 +1049,7 @@
 
 The filter gets two arguments: the process and the string of output.
 The string argument is normally a multibyte string, except:
-- if the process' input coding system is no-conversion or raw-text,
+- if the process's input coding system is no-conversion or raw-text,
   it is a unibyte string (the non-converted input), or else
 - if `default-enable-multibyte-characters' is nil, it is a unibyte
   string (the result of converting the decoded input multibyte
@@ -1061,7 +1061,7 @@
   CHECK_PROCESS (process);
   p = XPROCESS (process);
 
-  /* Don't signal an error if the process' input file descriptor
+  /* Don't signal an error if the process's input file descriptor
      is closed.  This could make debugging Lisp more difficult,
      for example when doing something like
 
@@ -2758,7 +2758,7 @@
 is the server process, CLIENT is the new process for the connection,
 and MESSAGE is a string.
 
-:plist PLIST -- Install PLIST as the new process' initial plist.
+:plist PLIST -- Install PLIST as the new process's initial plist.
 
 :server QLEN -- if QLEN is non-nil, create a server process for the
 specified FAMILY, SERVICE, and connection type (stream or datagram).
@@ -2788,21 +2788,21 @@
 for the connection with the following parameters:
 
 - The client's process name is constructed by concatenating the server
-process' NAME and a client identification string.
+process's NAME and a client identification string.
 - If the FILTER argument is non-nil, the client process will not get a
 separate process buffer; otherwise, the client's process buffer is a newly
-created buffer named after the server process' BUFFER name or process
+created buffer named after the server process's BUFFER name or process
 NAME concatenated with the client identification string.
 - The connection type and the process filter and sentinel parameters are
-inherited from the server process' TYPE, FILTER and SENTINEL.
-- The client process' contact info is set according to the client's
+inherited from the server process's TYPE, FILTER and SENTINEL.
+- The client process's contact info is set according to the client's
 addressing information (typically an IP address and a port number).
-- The client process' plist is initialized from the server's plist.
+- The client process's plist is initialized from the server's plist.
 
 Notice that the FILTER and SENTINEL args are never used directly by
 the server process.  Also, the BUFFER argument is not used directly by
 the server process, but via the optional :log function, accepted (and
-failed) connections may be logged in the server process' buffer.
+failed) connections may be logged in the server process's buffer.
 
 The original argument list, modified with the actual connection
 information, is available via the `process-contact' function.
@@ -3917,7 +3917,7 @@
 DEFUN ("accept-process-output", Faccept_process_output, Saccept_process_output,
        0, 4, 0,
        doc: /* Allow any pending output from subprocesses to be read by Emacs.
-It is read into the process' buffers or given to their filter functions.
+It is given to their filter functions.
 Non-nil arg PROCESS means do not return until some output has been received
 from PROCESS.
 
@@ -5187,7 +5187,8 @@
 
 DEFUN ("internal-default-process-filter", Finternal_default_process_filter,
        Sinternal_default_process_filter, 2, 2, 0,
-       doc: /* Function used as default process filter.  */)
+       doc: /* Function used as default process filter.
+This inserts the process's output into its buffer.  */)
   (Lisp_Object proc, Lisp_Object text)
 {
   struct Lisp_Process *p;
@@ -6411,7 +6412,8 @@
 
 DEFUN ("internal-default-process-sentinel", Finternal_default_process_sentinel,
        Sinternal_default_process_sentinel, 2, 2, 0,
-       doc: /* Function used as default sentinel for processes.  */)
+       doc: /* Function used as default sentinel for processes.
+This inserts a status message into the process's buffer.  */)
      (Lisp_Object proc, Lisp_Object msg)
 {
   Lisp_Object buffer, symbol;