From a773ea600c010490c54ea7c01efb66737f221d56 Mon Sep 17 00:00:00 2001
From: Raymond Toy <toy.raymond@gmail.com>
Date: Mon, 26 Sep 2016 19:50:47 -0700
Subject: [PATCH] Add documentation for run-program

 * Document :input and :output behavior when they are string streams.
 * Document :element-type and :external-format
---
 src/docs/cmu-user/extensions.tex | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/docs/cmu-user/extensions.tex b/src/docs/cmu-user/extensions.tex
index 9b21d2550..b5bbfff25 100644
--- a/src/docs/cmu-user/extensions.tex
+++ b/src/docs/cmu-user/extensions.tex
@@ -1099,7 +1099,8 @@ It is possible to run programs from Lisp by using the following function.
       \morekeys{\kwd{if-input-does-not-exist}}
       \yetmorekeys{\kwd{output} \kwd{if-output-exists}}
       \yetmorekeys{\kwd{error} \kwd{if-error-exists}}
-      \yetmorekeys{\kwd{status-hook}}}}
+      \yetmorekeys{\kwd{status-hook} \kwd{external-format}}
+      \yetmorekeys{\kwd{element-type}}}}
      
   \code{run-program} runs \var{program} in a child process.
   \var{Program} should be a pathname or string naming the program.
@@ -1154,6 +1155,11 @@ It is possible to run programs from Lisp by using the following function.
     already contains all the input for the process.  In this case
     \code{run-program} reads all the input from this stream before
     returning, so this cannot be used to interact with the process.
+    If \kwd{input} is a string stream, it is up to the caller to call
+    \code{string-encode} or other function to convert the string to
+    the appropriate encoding.  In either case, the least significant 8
+    bits of the \code{char-code} of each \code{character} is
+    sent to the program.
     
   \item[\kwd{if-input-does-not-exist}] This specifies what to do if
     the input file does not exist.  The following values are valid:
@@ -1172,7 +1178,10 @@ It is possible to run programs from Lisp by using the following function.
     \code{process-output} slot contains an input stream from which you
     can read the program's output.  \kwd{output} can also be a stream
     in which case all output from the process is written to this
-    stream. 
+    stream.  If \kwd{output} is a string-stream, each octet read from
+    the program is converted to a character using \code{code-char}.
+    It is up to the caller to convert this using the appropriate
+    external format to create the desired encoded string.
     
   \item[\kwd{if-output-exists}] This specifies what to do if the
     output file already exists.  The following values are valid:
@@ -1197,6 +1206,15 @@ It is possible to run programs from Lisp by using the following function.
     the process changes status.  This is especially useful when
     specifying \kwd{wait} as \nil.  The function takes the process as
     a required argument.
+
+  \item[\kwd{external-format}] This specifies the external format to
+    use for streams created for \code{run-program}.  This does not
+    apply to string streams passed in as \kwd{input} or \kwd{output}
+    parameters.
+
+  \item[\kwd{element-type}] If streams are created \code{run-program},
+    use this as the \kwd{element-type} for the stream.  Defaults to
+    \code{BASE-CHAR}. 
     
 %   \item[\kwd{before-execve}] This specifies a function to run in the
 %     child process before it becomes the program to run.  This is
-- 
GitLab