[Emacs-diffs] /srv/bzr/emacs/emacs-24 r107840: More small edits for doc/lispref/processes.texi

[Glenn Morris]

------------------------------------------------------------
revno: 107840
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Sun 2012-04-15 17:50:58 -0700
message:
  More small edits for doc/lispref/processes.texi 
  
  * doc/lispref/processes.texi (Process Information, Input to Processes)
  (Signals to Processes, Output from Processes, Process Buffers)
  (Filter Functions, Decoding Output): Copyedits.
modified:
  doc/lispref/ChangeLog
  doc/lispref/processes.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-04-15 01:58:41 +0000
+++ b/doc/lispref/ChangeLog     2012-04-16 00:50:58 +0000
@@ -1,3 +1,9 @@
+2012-04-16  Glenn Morris  <address@hidden>
+
+       * processes.texi (Process Information, Input to Processes)
+       (Signals to Processes, Output from Processes, Process Buffers)
+       (Filter Functions, Decoding Output): Copyedits.
+
 2012-04-15  Glenn Morris  <address@hidden>
 
        * processes.texi (Processes, Subprocess Creation, Shell Arguments):

=== modified file 'doc/lispref/processes.texi'
--- a/doc/lispref/processes.texi        2012-04-15 01:58:41 +0000
+++ b/doc/lispref/processes.texi        2012-04-16 00:50:58 +0000
@@ -726,17 +726,17 @@
 @section Process Information
 
   Several functions return information about processes.
address@hidden is provided for interactive use.
 
address@hidden Command list-processes &optional query-only
address@hidden 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 address@hidden then it lists only processes
+If @var{query-only} is address@hidden, it only lists processes
 whose query flag is address@hidden  @xref{Query Before Exit}.
 @end deffn
 
@@ -752,8 +752,8 @@
 @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
address@hidden if there is none.
 
 @smallexample
 @group
@@ -772,7 +772,7 @@
 @smallexample
 @group
 (process-command (get-process "shell"))
-     @result{} ("/bin/csh" "-i")
+     @result{} ("bash" "-i")
 @end group
 @end smallexample
 @end defun
@@ -780,11 +780,10 @@
 @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
address@hidden, 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
address@hidden(@var{hostname} @var{service})} for a network process, and
address@hidden(@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
@@ -792,7 +791,8 @@
 @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
address@hidden for a complete list):
 
 @table @code
 @item :buffer
@@ -829,7 +829,7 @@
 @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
@@ -869,12 +869,6 @@
 (process-status (get-buffer "*shell*"))
      @result{} run
 @end group
address@hidden
-x
-     @result{} #<process xx<1>>
-(process-status x)
-     @result{} exit
address@hidden group
 @end smallexample
 
 For a network connection, @code{process-status} returns one of the symbols
@@ -912,13 +906,9 @@
 
 @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
address@hidden (@pxref{Coding Systems}).  The value has this form:
-
address@hidden
-(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
address@hidden 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
@@ -958,6 +948,7 @@
 specify the process to send input to, and the input data to send.  The
 data appears on the ``standard input'' of the subprocess.
 
address@hidden 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
@@ -984,26 +975,14 @@
 
 @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
-
-
address@hidden
----------- Buffer: *shell* ----------
-...
-introduction.texi               syntax-tables.texi~
-introduction.texi~              text.texi
-introduction.txt                text.texi~
-...
----------- Buffer: *shell* ----------
address@hidden group
 @end smallexample
 @end defun
 
@@ -1019,7 +998,6 @@
 @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
@@ -1050,7 +1028,7 @@
 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.
 
@@ -1059,7 +1037,7 @@
 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}.
@@ -1103,6 +1081,8 @@
 @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
address@hidden FIXME?  Never heard of C-b being used for this.  In readline, eg
address@hidden bash, that is backward-word.
 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
 Emacs.
 @end defun
@@ -1127,11 +1107,12 @@
 
 @defun signal-process process signal
 This function sends a signal to process @var{process}.  The argument
address@hidden specifies which signal to send; it should be an integer.
address@hidden 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
@@ -1141,10 +1122,10 @@
 
   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
@@ -1164,7 +1145,7 @@
 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
 address@hidden 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.
@@ -1233,9 +1214,9 @@
 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},
address@hidden 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
@@ -1301,19 +1282,20 @@
   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
address@hidden is address@hidden, the error-catching is turned
-off.  This makes it possible to use the Lisp debugger to debug the
address@hidden is address@hidden, 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:
 
address@hidden Filter Example}
 @smallexample
 @group
 (defun ordinary-insertion-filter (proc string)
@@ -1323,7 +1305,7 @@
 @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)))
@@ -1331,14 +1313,8 @@
 @end group
 @end smallexample
 
address@hidden
-The reason to use @code{with-current-buffer}, rather than using
address@hidden to save and restore the current buffer, is so as
-to preserve the change in point made by the second call to
address@hidden
-
   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
@@ -1349,12 +1325,16 @@
 previously, eliminate the variable @code{moving} and call
 @code{goto-char} unconditionally.
 
address@hidden
   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.
address@hidden 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
@@ -1372,7 +1352,7 @@
 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
@@ -1392,7 +1372,7 @@
 (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~
@@ -1448,8 +1428,8 @@
 @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
@@ -1467,7 +1447,7 @@
 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