From 4d0224badf5bdf99d7a27977ffc4d758122debd9 Mon Sep 17 00:00:00 2001
From: Julian Noble <julian@precisium.com.au>
Date: Sat, 5 Aug 2023 02:38:25 +1000
Subject: [PATCH] README.md - more run-command info

---
 README.md | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 053b551..5fc24e0 100644
--- a/README.md
+++ b/README.md
@@ -20,15 +20,26 @@ BSD license
     `x@end/@@k1.= list {k1 aaa} {k1 bb}`  returns bbb   
     
     There are many more pattern-matching features yet to be documented.
-- easy execution of externals commands with return of stdout, stderr and the exitcode of the process
+- easy execution of externals commands with return of stdout, stderr and the exitcode of the process   
+    The run... commands use a very basic repl-telemetry system to output more information to the console than just the return value,   
+    but in a way which makes the return value clear. The telemetry only outputs if the command is the first word on the commandline.  
     - `run <comand> ...`   
        (return exitcode of process - and allows process writes to stderr/stdout to appear in console as they occur)
-    - `runout <command> ...`   
+    - `runout [-n] <command> ...`   
        (return stdout of process - no output until completion)
-    - `runerr <command> ...`   
+    - `runerr [-n] <command> ...`   
        (return stderr of process - no output until completion)
-    - `runx  <command> ...`
+    - `runx [-n] <command> ...`
        (return a dict of stdout stderr exitcode - no output until completion)
+       
+    The run... commands attempt to make it clear if an called process outputs a trailing newline by displaying a trailing blank line.   
+    The optional `-n` argument can be used to suppress a trailing newline.
+    `runout -n pwd` is thus **similar** to Tcl's `exec pwd`   
+    For simple cases `exec <command>` is fine - but the equivalent `runout -n <command>` when used in the shell will display exitcode and stderr separately (whilst returning only stdout)
+    exec will return stdout and stderr together.  
+    If you are on a unix-like platform, or a windows platform which has something like msys2 to provide commands like 'which' and 'grep' in the path:   
+    Try `runx -n which grep nonexistant` vs `exec which grep nonexistant`  to see the difference in terms of easy access to what was written to stderr vs stdout.   
+    The run... commands are intended as a supplement for rather than a replacement for Tcl's exec/open.   
 - namespace browser (contextual - allowing running of commands within the active namespace - analogous to 'cd' for directories)
     -  `n/`  - display child namespaces of current namespace  (alias `:/`)   
          also `n/ <globpattern>` to restrict output