*** empty log message ***

1 files changed, 128 insertions, 78 deletions

diff --git a/lispref/processes.texi b/lispref/processes.texi
index eb26970651b..e9106f3a768 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/processes
 @node Processes, System Interface, Abbrevs, Top
@@ -80,18 +80,20 @@ Expansion}).
 
   Each of the subprocess-creating functions has a @var{buffer-or-name}
 argument which specifies where the standard output from the program will
-go.  If @var{buffer-or-name} is @code{nil}, that says to discard the
-output unless a filter function handles it.  (@xref{Filter Functions},
-and @ref{Read and Print}.)  Normally, you should avoid having multiple
-processes send output to the same buffer because their output would be
-intermixed randomly.
+go.  It should be a buffer or a buffer name (which will create the
+buffer if it does not already exist).  It can also be @code{nil}, which
+says to discard the output unless a filter function handles it.
+(@xref{Filter Functions}, and @ref{Read and Print}.)  Normally, you
+should avoid having multiple processes send output to the same buffer
+because their output would be intermixed randomly.
 
 @cindex program arguments
   All three of the subprocess-creating functions have a @code{&rest}
 argument, @var{args}.  The @var{args} must all be strings, and they are
 supplied to @var{program} as separate command line arguments.  Wildcard
-characters and other shell constructs are not allowed in these strings,
-since they are passed directly to the specified program.  
+characters and other shell constructs have no special meanings in these
+strings, since the whole strings are passed directly to the specified
+program.
 
   @strong{Please note:} The argument @var{program} contains only the
 name of the program; it may not contain any command-line arguments.  You
@@ -144,15 +146,19 @@ user types another @kbd{C-g}, that kills the subprocess instantly with
 @code{SIGKILL} and quits immediately.  @xref{Quitting}.
 
   The synchronous subprocess functions returned @code{nil} in version
-18.  In version 19, they return an indication of how the process
-terminated.
+18.  Now they return an indication of how the process terminated.
+
+  The output from a synchronous subprocess is generally decoded using a
+coding system, much like text read from a file.  The input sent to a
+subprocess by @code{call-process-region} is encoded using a coding
+system, much like text written into a file.  @xref{Coding Systems}.
 
 @defun call-process program &optional infile destination display &rest args
 This function calls @var{program} in a separate process and waits for
 it to finish.
 
 The standard input for the process comes from file @var{infile} if
-@var{infile} is not @code{nil} and from @file{/dev/null} otherwise.
+@var{infile} is not @code{nil}, and from @file{/dev/null} otherwise.
 The argument @var{destination} says where to put the process output.
 Here are the possibilities:
 
@@ -247,8 +253,9 @@ of @code{call-process}:
 @defun call-process-region start end program &optional delete destination display &rest args
 This function sends the text between @var{start} to @var{end} as
 standard input to a process running @var{program}.  It deletes the text
-sent if @var{delete} is non-@code{nil}; this is useful when @var{buffer}
-is @code{t}, to insert the output in the current buffer.
+sent if @var{delete} is non-@code{nil}; this is useful when
+@var{destination} is @code{t}, to insert the output in the current
+buffer in place of the input.
 
 The arguments @var{destination} and @var{display} control what to do
 with the output from the subprocess, and whether to update the display
@@ -305,6 +312,12 @@ inputinput@point{}
 @end smallexample
 @end defun
 
+@tindex shell-command-to-string
+@defun shell-command-to-string command
+This function executes @var{command} (a string) as a shell command,
+then returns the command's output as a string.
+@end defun
+
 @node MS-DOS Subprocesses
 @section MS-DOS Subprocesses
 
@@ -346,8 +359,8 @@ This function creates a new asynchronous subprocess and starts the
 program @var{program} running in it.  It returns a process object that
 stands for the new subprocess in Lisp.  The argument @var{name}
 specifies the name for the process object; if a process with this name
-already exists, then @var{name} is modified (by adding @samp{<1>}, etc.)
-to be unique.  The buffer @var{buffer-or-name} is the buffer to
+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.
 
 The remaining arguments, @var{args}, are strings that specify command
@@ -388,7 +401,8 @@ Process my-process finished
 This function is like @code{start-process} except that it uses a shell
 to execute the specified command.  The argument @var{command} is a shell
 command name, and @var{command-args} are the arguments for the shell
-command.
+command.  The variable @code{shell-file-name} specifies which shell to
+use.
 @end defun
 
 @defvar process-connection-type
@@ -400,11 +414,11 @@ used, when available.  Otherwise, pipes are used.
 
 @sc{pty}s are usually preferable for processes visible to the user, as
 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
-etc.) to work between the process and its children whereas pipes do not.
-For subprocesses used for internal purposes by programs, it is often
-better to use a pipe, because they are more efficient.  In addition, the
-total number of @sc{pty}s is limited on many systems and it is good not
-to waste them.
+etc.) to work between the process and its children, whereas pipes do
+not.  For subprocesses used for internal purposes by programs, it is
+often better to use a pipe, because they are more efficient.  In
+addition, the total number of @sc{pty}s is limited on many systems and
+it is good not to waste them.
 
 The value @code{process-connection-type} is used when
 @code{start-process} is called.  So you can specify how to communicate
@@ -535,6 +549,13 @@ process is started and remains constant as long as the process exists.
 This function returns the name of @var{process}.
 @end defun
 
+@tindex process-contact
+@defun process-contact process
+This function returns @code{t} for an ordinary child process, and
+@code{(@var{hostname} @var{service})} for a net connection
+(@pxref{Network}).
+@end defun
+
 @defun process-status process-name
 This function returns the status of @var{process-name} as a symbol.
 The argument @var{process-name} must be a process, a buffer, a
@@ -582,8 +603,8 @@ For a network connection, @code{process-status} returns one of the symbols
 @code{open} or @code{closed}.  The latter means that the other side
 closed the connection, or Emacs did @code{delete-process}.
 
-In earlier Emacs versions (prior to version 19), the status of a network
-connection was @code{run} if open, and @code{exit} if closed.
+In Emacs version 18, the status of a network connection was @code{run}
+if open, and @code{exit} if closed.
 @end defun
 
 @defun process-exit-status process
@@ -600,6 +621,26 @@ instead of a terminal (see @code{process-connection-type} in
 @ref{Asynchronous Processes}).
 @end defun
 
+@tindex process-coding-system
+@defun process-coding-system process
+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
+@end defun
+
+@tindex set-process-coding-system
+@defun set-process-coding-system process decoding-system encoding-system
+This function specifies the coding systems to use for subsequent output
+from and input to @var{process}.  It will use @var{decoding-system} to
+decode subprocess output, and @var{encoding-system} to encode subprocess
+input.
+@end defun
+
 @node Input to Processes
 @section Sending Input to Processes
 @cindex process input
@@ -614,6 +655,10 @@ data appears on the ``standard input'' of the subprocess.
 the other characters, to force them through.  For most programs,
 these @sc{eof}s do no harm.
 
+  Subprocess input is normally encoded using a coding system before the
+subprocess receives it, much like text written into a file.
+@xref{Coding Systems}.
+
 @defun process-send-string process-name string
 This function sends @var{process-name} the contents of @var{string} as
 standard input.  The argument @var{process-name} must be a process or
@@ -744,10 +789,11 @@ This function stops the process @var{process-name} by sending the
 signal @code{SIGTSTP}.  Use @code{continue-process} to resume its
 execution.
 
-On systems with job control, the ``stop character'' (usually @kbd{C-z})
-sends this signal (outside of Emacs).  When @var{current-group} is
-non-@code{nil}, you can think of this function as ``typing @kbd{C-z}''
-on the terminal Emacs uses to communicate with the subprocess.
+On systems with job control, outside of Emacs)\, the ``stop character''
+(usually @kbd{C-z}) normally sends this signal.  When
+@var{current-group} is non-@code{nil}, you can think of this function as
+``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
+subprocess.
 @end defun
 
 @defun continue-process &optional process-name current-group
@@ -775,6 +821,10 @@ 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.
 
+  Subprocess output is normally decoded using a coding system before the
+buffer or filter function receives it, much like text read from a file.
+@xref{Coding Systems}.
+
 @menu
 * Process Buffers::       If no filter, output is put in a buffer.
 * Filter Functions::      Filter functions accept output from the process.
@@ -828,8 +878,8 @@ example of a filter function that uses @code{process-mark} is found at
 the end of the following section.
 
 When the user is expected to enter input in the process buffer for
-transmission to the process, the process marker is useful for
-distinguishing the new input from previous output.
+transmission to the process, the process marker separates the new input
+from previous output.
 @end defun
 
 @defun set-process-buffer process buffer
@@ -841,7 +891,7 @@ associated with no buffer.
 @defun get-buffer-process buffer-or-name
 This function returns the process associated with @var{buffer-or-name}.
 If there are several processes associated with it, then one is chosen.
-(Presently, the one chosen is the one most recently created.)  It is
+(Currently, the one chosen is the one most recently created.)  It is
 usually a bad idea to have more than one process associated with the
 same buffer.
 
@@ -867,9 +917,9 @@ 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.
 
-  A filter function must accept two arguments: the associated process and
-a string, which is the output.  The function is then free to do whatever it
-chooses with the 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.
 
   A filter function runs only while Emacs is waiting (e.g., for terminal
 input, or for time to elapse, or for process output).  This avoids the
@@ -897,61 +947,61 @@ filter function.  @xref{Debugger}.
 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 use @code{unwind-protect}
-to make sure to restore the previous current buffer.  They should also
-update the process marker, and in some cases update the value of point.
-Here is how to do these things:
+semipermanently, these filter functions must save and restore the
+current buffer.  They should also update the process marker, and in some
+cases update the value of point.  Here is how to do these things:
 
 @smallexample
 @group
 (defun ordinary-insertion-filter (proc string)
-  (let ((old-buffer (current-buffer)))
-    (unwind-protect
-        (let (moving)
-          (set-buffer (process-buffer proc))
-          (setq moving (= (point) (process-mark proc)))
+  (with-current-buffer (process-buffer proc)
+    (let ((moving (= (point) (process-mark proc))))
 @end group
 @group
-          (save-excursion
-            ;; @r{Insert the text, moving the process-marker.}
-            (goto-char (process-mark proc))
-            (insert string)
-            (set-marker (process-mark proc) (point)))
-          (if moving (goto-char (process-mark proc))))
-      (set-buffer old-buffer))))
+      (save-excursion
+        ;; @r{Insert the text, advancing the process marker.}
+        (goto-char (process-mark proc))
+        (insert string)
+        (set-marker (process-mark proc) (point)))
+      (if moving (goto-char (process-mark proc))))))
 @end group
 @end smallexample
 
 @noindent
-The reason to use an explicit @code{unwind-protect} rather than letting
-@code{save-excursion} restore the current buffer is so as to preserve
-the change in point made by @code{goto-char}.
+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
-@code{unwind-protect}:
+@code{with-current-buffer} construct:
 
 @smallexample
 (display-buffer (process-buffer proc))
 @end smallexample
 
-  To force point to move to the end of the new output no matter where
-it was previously, eliminate the variable @code{moving} and call
+  To force point to the end of the new output, no matter where it was
+previously, eliminate the variable @code{moving} and call
 @code{goto-char} unconditionally.
 
-  In earlier Emacs versions, every filter function that did regexp
-searching or matching had to explicitly save and restore the match data.
-Now Emacs does this automatically; filter functions never need to do it
-explicitly.  @xref{Match Data}.
+  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}.
 
   A filter function that writes the output into the buffer of the
 process 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}.
+insert into a dead buffer, it will get an error.  The expression
+@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
+if the buffer is dead.
 
   The output to the function 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.
+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
+sure to handle the case where one of these strings is split across two
+or more batches of output.
 
 @defun set-process-filter process filter
 This function gives @var{process} the filter function @var{filter}.  If
@@ -1007,15 +1057,15 @@ there is no filter function:
 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
 ;;   @r{and make sure that buffer is shown in some window.}
 (defun my-process-filter (proc str)
-    (let ((cur (selected-window))
-          (pop-up-windows t))
-      (pop-to-buffer my-shell-buffer)
+  (let ((cur (selected-window))
+        (pop-up-windows t))
+    (pop-to-buffer my-shell-buffer)
 @end group
 @group
-      (goto-char (point-max))
-      (insert str)
-      (set-marker (process-mark proc) (point-max))
-      (select-window cur)))
+    (goto-char (point-max))
+    (insert str)
+    (set-marker (process-mark proc) (point-max))
+    (select-window cur)))
 @end group
 @end smallexample
 @end ignore
@@ -1113,10 +1163,10 @@ programs was running when the sentinel was started.  However, if
 off.  This makes it possible to use the Lisp debugger to debug the
 sentinel.  @xref{Debugger}.
 
-  In earlier Emacs versions, every sentinel that did regexp searching or
-matching had to explicitly save and restore the match data.  Now Emacs
-does this automatically; sentinels never need to do it explicitly.
-@xref{Match Data}.
+  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}.
 
 @defun set-process-sentinel process sentinel
 This function associates @var{sentinel} with @var{process}.  If
@@ -1156,10 +1206,10 @@ was not.
 @section Transaction Queues
 @cindex transaction queue
 
-You can use a @dfn{transaction queue} for more convenient communication
-with subprocesses using transactions.  First use @code{tq-create} to
-create a transaction queue communicating with a specified process.  Then
-you can call @code{tq-enqueue} to send a transaction.
+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
+@code{tq-enqueue} to send a transaction.
 
 @defun tq-create process
 This function creates and returns a transaction queue communicating with