Lisp manual -- improve discussion of ptys vs pipes.

* processes.texi (Asynchronous Processes): Make the pty vs pipe
discussion more prominent.

2 files changed, 26 insertions, 18 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 154b4487d5e..782b6930a84 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2012-06-24  Thien-Thi Nguyen  <ttn@gnuvola.org>
+
+        * processes.texi (Asynchronous Processes): Make the pty vs pipe
+        discussion more prominent.
+
 2012-06-23  Eli Zaretskii  <eliz@gnu.org>
 
         * commands.texi (Misc Events): Document the language-change event.
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index d1bfa0e936d..fc166268e4e 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -541,16 +541,29 @@ is decoded in the same way as for @code{call-process}.
 @section Creating an Asynchronous Process
 @cindex asynchronous subprocess
 
-  After an @dfn{asynchronous process} is created, Emacs and the subprocess
-both continue running immediately.  The process thereafter runs
-in parallel with Emacs, and the two can communicate with each other
-using the functions described in the following sections.  However,
+  In this section, we describe how to create an @dfn{asynchronous
+process}.  After an asynchronous process is created, it runs in
+parallel with Emacs, and Emacs can communicate with it using the
+functions described in the following sections (@pxref{Input to
+Processes}, and @pxref{Output from Processes}).  Note that process
 communication is only partially asynchronous: Emacs sends data to the
 process only when certain functions are called, and Emacs accepts data
-from the process only when Emacs is waiting for input or for a time
-delay.
-
-  Here we describe how to create an asynchronous process.
+from the process only while waiting for input or for a time delay.
+
+@cindex pty
+@cindex pipe
+  An asynchronous process is controlled either via a @dfn{pty}
+(pseudo-terminal) or a @dfn{pipe}.  The choice of pty or pipe is made
+when creating the process, based on the value of the variable
+@code{process-connection-type} (see below).  Ptys are usually
+preferable for processes visible to the user, as in Shell mode,
+because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)
+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, and because
+they are immune to stray character injections that ptys introduce for
+large (around 500 byte) messages.  Also, the total number of ptys is
+limited on many systems and it is good not to waste them.
 
 @defun start-process name buffer-or-name program &rest args
 This function creates a new asynchronous subprocess and starts the
@@ -652,20 +665,10 @@ can also be executed on remote hosts, depending on @code{default-directory}.
 @end defun
 
 @defvar process-connection-type
-@cindex pipes
-@cindex @acronym{PTY}s
 This variable controls the type of device used to communicate with
 asynchronous subprocesses.  If it is non-@code{nil}, then @acronym{PTY}s are
 used, when available.  Otherwise, pipes are used.
 
-@acronym{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 @acronym{PTY}s is limited on many systems and
-it is good not to waste them.
-
 The value of @code{process-connection-type} takes effect when
 @code{start-process} is called.  So you can specify how to communicate
 with one subprocess by binding the variable around the call to