[slime-cvs] CVS slime/doc

[mkoeppe]

Update of /project/slime/cvsroot/slime/doc
In directory clnet:/tmp/cvs-serv5212

Modified Files:
	slime.texi 
Log Message:
Document limitations of *USE-DEDICATED-OUTPUT-STREAM* = t.


--- /project/slime/cvsroot/slime/doc/slime.texi	2007/01/27 18:42:35	1.54
+++ /project/slime/cvsroot/slime/doc/slime.texi	2007/08/26 18:42:23	1.55
@@ -10,7 +10,7 @@
 
 @set EDITION 2.0
 @c @set UPDATED @today{}
- at set UPDATED @code{$Date: 2007/01/27 18:42:35 $}
+ at set UPDATED @code{$Date: 2007/08/26 18:42:23 $}
 @set TITLE SLIME User Manual
 @settitle @value{TITLE}, version @value{EDITION}
 
@@ -518,7 +518,7 @@
 @subsection Programming commands
 
 Programming commands are divided into the following categories:
- at strong{Completion, Documentation, Coss-reference, Finding
+ at strong{Completion, Documentation, Cross-reference, Finding
 definitions, Macro-expansion, and Disassembly}, discussed in
 separate sections below.
 
@@ -1796,12 +1796,20 @@
 @end example
 
 @item SWANK:*USE-DEDICATED-OUTPUT-STREAM*
-This variable controls an optimization for sending printed output from
-Lisp to Emacs. When @code{t} a separate socket is established solely for
-Lisp to send printed output to Emacs through. Without the optimization
-it is necessary to send output in protocol-messages to Emacs which must
-then be decoded, and this doesn't always keep up if Lisp starts
-``spewing'' copious output.
+This variable controls whether to use an unsafe efficiency hack for
+sending printed output from Lisp to Emacs.  The default is @code{nil},
+don't use it, and is strongly recommended to keep.
+
+When @code{t}, a separate socket is established solely for Lisp to send
+printed output to Emacs through, which is faster than sending the output
+in protocol-messages to Emacs.  However, as nothing can be guaranteed
+about the timing between the dedicated output stream and the stream of
+protocol messages, the output of a Lisp command can arrive before or
+after the corresponding REPL results.  Thus output and REPL results can
+end up in the wrong order, or even interleaved, in the REPL buffer.
+Using a dedicated output stream also makes it more difficult to
+communicate to a Lisp running on a remote host via SSH
+(@pxref{Connecting to a remote lisp}).  
 
 @item SWANK:*DEDICATED-OUTPUT-STREAM-PORT*
 When @code{*USE-DEDICATED-OUTPUT-STREAM*} is @code{t} the stream will
@@ -1873,7 +1881,7 @@
 has the side-effect of giving the entire world access to your lisp
 image, so we're not going to talk about it} and we'll only have one
 port open we want to tell swank to not use an extra connection for
-output:
+output (this is actually the default in current SLIME):
 
 @example
 (setf swank:*use-dedicated-output-stream* nil)