[Emacs-diffs] /srv/bzr/emacs/emacs-24 r108715: Lisp manual -- improve discussion of ptys vs pipes.

[Chong Yidong]

------------------------------------------------------------
revno: 108715
author: Thien-Thi Nguyen <address@hidden>
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2012-06-24 17:30:35 +0800
message:
  Lisp manual -- improve discussion of ptys vs pipes.
  
  * processes.texi (Asynchronous Processes): Make the pty vs pipe
  discussion more prominent.
modified:
  doc/lispref/ChangeLog
  doc/lispref/processes.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-06-23 12:39:23 +0000
+++ b/doc/lispref/ChangeLog     2012-06-24 09:30:35 +0000
@@ -1,3 +1,8 @@
+2012-06-24  Thien-Thi Nguyen  <address@hidden>
+
+       * processes.texi (Asynchronous Processes): Make the pty vs pipe
+       discussion more prominent.
+
 2012-06-23  Eli Zaretskii  <address@hidden>
 
        * commands.texi (Misc Events): Document the language-change event.

=== modified file 'doc/lispref/processes.texi'
--- a/doc/lispref/processes.texi        2012-06-22 21:17:42 +0000
+++ b/doc/lispref/processes.texi        2012-06-24 09:30:35 +0000
@@ -541,16 +541,29 @@
 @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.
+from the process only while waiting for input or for a time delay.
 
-  Here we describe how to create an asynchronous process.
address@hidden pty
address@hidden 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
address@hidden (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 @@
 @end defun
 
 @defvar process-connection-type
address@hidden pipes
address@hidden @acronym{PTY}s
 This variable controls the type of device used to communicate with
 asynchronous subprocesses.  If it is address@hidden, then @acronym{PTY}s are
 used, when available.  Otherwise, pipes are used.
 
address@hidden 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