[Emacs-diffs] emacs-25 68218d8: Document default process sentinel more prominently

[Eli Zaretskii]

branch: emacs-25
commit 68218d82649c7336874438a7010a180ad3e50803
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Document default process sentinel more prominently
    
    * doc/lispref/processes.texi (Asynchronous Processes): Mention the
    defaults for process filter and sentinel.  Provide cross-references.
    (Process Information): Provide cross-references to where filters
    and sentinels are described.
    (Filter Functions): Add an index entry for "default filter".
    (Sentinels): Add a few status messages not documented previously.
    Resolve the "killed" confusion.  Document and describe the default
    sentinel.  (Bug#22220)
---
 doc/lispref/processes.texi |   48 ++++++++++++++++++++++++++++++++++---------
 1 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 0ce696a..41255e7 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -737,10 +737,12 @@ If @var{stopped} is address@hidden, start the process in 
the
 stopped state.
 
 @item :filter @var{filter}
-Initialize the process filter to @var{filter}.
+Initialize the process filter to @var{filter}.  If not specified, a
+default filter will be provided.  @xref{Filter Functions}.
 
 @item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.
+Initialize the process sentinel to @var{sentinel}.  If not specified,
+a default sentinel will be used.  @xref{Sentinels}.
 
 @item :stderr @var{stderr}
 Associate @var{stderr} with the standard error of the process.
@@ -789,10 +791,12 @@ If @var{stopped} is address@hidden, start the process in 
the
 stopped state.
 
 @item :filter @var{filter}
-Initialize the process filter to @var{filter}.
+Initialize the process filter to @var{filter}.  If not specified, a
+default filter will be provided.  @xref{Filter Functions}.
 
 @item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.
+Initialize the process sentinel to @var{sentinel}.  If not specified,
+a default sentinel will be used.  @xref{Sentinels}.
 @end table
 
 The original argument list, modified with the actual connection
@@ -922,9 +926,10 @@ For a network process, the values include (see
 @item :buffer
 The associated value is the process buffer.
 @item :filter
-The associated value is the process filter function.
+The associated value is the process filter function.  @xref{Filter
+Functions}.
 @item :sentinel
-The associated value is the process sentinel function.
+The associated value is the process sentinel function.  @xref{Sentinels}.
 @item :remote
 In a connection, the address in internal format of the remote peer.
 @item :local
@@ -1379,6 +1384,7 @@ subprocess with a @code{SIGHUP} signal (@pxref{Signals to 
Processes}).
 @cindex filter function
 @cindex process filter
 
address@hidden default filter function of a process
   A process @dfn{filter function} is a function that receives the
 standard output from the associated process.  @emph{All} output from
 that process is passed to the filter.  The default filter simply
@@ -1632,21 +1638,43 @@ also called if the process exits.  The sentinel 
receives two
 arguments: the process for which the event occurred, and a string
 describing the type of event.
 
address@hidden default sentinel function of a process
+  If no sentinel function was specified for a process, it will use the
+default sentinel function, which inserts a message in the process's
+buffer with the process name and the string describing the event.
+
   The string describing the event looks like one of the following:
 
address@hidden FIXME?  Also "killed\n" - see example below?
 @itemize @bullet
 @item
 @code{"finished\n"}.
 
 @item
address@hidden"exited abnormally with code @var{exitcode}\n"}.
address@hidden"deleted\n"}.
+
address@hidden
address@hidden"exited abnormally with code @var{exitcode} (core dumped)\n"}.
+The ``core dumped'' part is optional, and only appears if the process
+dumped core.
+
address@hidden
address@hidden"failed with code @var{fail-code}\n"}.
+
address@hidden
address@hidden"@var{signal-description} (core dumped)\n"}.  The
address@hidden is a system-dependent textual description of
+a signal, e.g., @code{"killed"} for @code{SIGKILL}.  The ``core
+dumped'' part is optional, and only appears if the process dumped
+core.
+
address@hidden
address@hidden"open from @var{host-name}\n"}.
 
 @item
address@hidden"@var{name-of-signal}\n"}.
address@hidden"open\n"}.
 
 @item
address@hidden"@var{name-of-signal} (core dumped)\n"}.
address@hidden"connection broken by remote peer\n"}.
 @end itemize
 
   A sentinel runs only while Emacs is waiting (e.g., for terminal