From fec1a3fa29d8a9a6ea5f69bfc6d381c0a68f79a6 Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <tunes@google.com>
Date: Mon, 31 Aug 2015 00:36:59 -0400
Subject: [PATCH] Convert the README to markdown

---
 README => README.md | 82 +++++++++++++++++++++++++++++----------------
 1 file changed, 53 insertions(+), 29 deletions(-)
 rename README => README.md (88%)

diff --git a/README b/README.md
similarity index 88%
rename from README
rename to README.md
index dd242e5..f93173f 100644
--- a/README
+++ b/README.md
@@ -1,4 +1,8 @@
-INFERIOR-SHELL
+INFERIOR-SHELL: spawning shell commands and pipes from Common Lisp
+==================================================================
+
+What is inferior-shell?
+-----------------------
 
 This CL library allows you to spawn local or remote processes and shell pipes.
 It lets me use CL in many cases where I would previously write shell scripts.
@@ -33,9 +37,10 @@ Example use of inferior-shell, from the rpm system:
    :host host))
 
 
-==== Limitations ====
+Limitations
+-----------
 
-By default, inferior-shell uses asdf-driver:run-program
+By default, inferior-shell uses uiop:run-program
 as its universal execution backend, and has its limitations,
 which are as follows.
 
@@ -46,31 +51,28 @@ IOlib requires C compilation and linking, and may or may not support Windows.
 executor only supports select implementations.
 A future extension to inferior-shell may use IOlib as a backend.
 
-Second, there is currently limited support for input redirection.
-The only possible input redirection is from /dev/null
-or by inheriting the parent's standard input
-when running in :interactive mode.
-However, using shell redirection, you can also redirect input from a file,
-or from a numbered file descriptor (except 0, 1, 2).
-
-Finally, supported platforms at this time include:
+Second, supported platforms at this time include:
 ABCL, Allegro, CLISP, ClozureCL, CMUCL, ECL, LispWorks, RMCL, SBCL, SCL, XCL.
 Platforms NOT (yet) supported include:
 CormanLisp (untested), GCL (untested), Genera (unimplemented), MKCL (untested).
 On supported platforms, inferior-shell works on both Unix and Windows.
 
 
-==== Exported Functionality ====
+Exported Functionality
+----------------------
 
 The inferior-shell library creates a package INFERIOR-SHELL,
 that exports the following macros and functions:
 
-PARSE-PROCESS-SPEC SPEC
+* `PARSE-PROCESS-SPEC SPEC`
+
   parse an expression in the process-spec mini-language into
   objects specifying a pipeline of processes to be executed.
   See the PROCESS-SPEC mini-language below.
 
-PRINT-PROCESS-SPEC SPEC &OPTIONAL OUTPUT
+
+* `PRINT-PROCESS-SPEC SPEC &OPTIONAL OUTPUT`
+
   print a process specification to given OUTPUT
   into a portable form usable by a Unix shell.
   OUTPUT is as per FORMAT's stream output argument,
@@ -79,18 +81,26 @@ PRINT-PROCESS-SPEC SPEC &OPTIONAL OUTPUT
   a CONS to be parsed by PARSE-PROCESS-SPEC,
   or a string for a process-spec that has already been formatted.
 
-*CURRENT-HOST-NAMES*
+
+* `*CURRENT-HOST-NAMES*`
+
   a variable, a list of strings, the aliases for the localhost.
   You may need to initialize it if the defaults don't suffice.
 
-CURRENT-HOST-NAME-P X
+
+* `CURRENT-HOST-NAME-P X`
+
   a function, returns true if X is a string member of *CURRENT-HOST-NAMES*
 
-INITIALIZE-CURRENT-HOST-NAMES
+
+* `INITIALIZE-CURRENT-HOST-NAMES`
+
   function that initializes the *CURRENT-HOST-NAMES*
   with "localhost" and the results from $(hostname -s) and $(hostname -f).
 
-RUN CMD &KEY ON-ERROR TIME SHOW HOST OUTPUT
+
+* `RUN CMD &KEY ON-ERROR TIME SHOW HOST OUTPUT`
+
   RUN will execute the given command CMD, which can be
   a CONS to be parsed by PARSE-PROCESS-SPEC,
   a PROCESS-SPEC object already parsed,
@@ -125,37 +135,48 @@ RUN CMD &KEY ON-ERROR TIME SHOW HOST OUTPUT
   On Unix, simple commands on localhost are executed directly, but
   remote commands and pipes are executed by spawning a shell.
 
-RUN/NIL CMD &KEY ON-ERROR TIME SHOW HOST
+* `RUN/NIL CMD &KEY ON-ERROR TIME SHOW HOST`
+
   RUN/NIL is a shorthand for RUN with :INPUT :OUTPUT :ERROR-OUTPUT bound to NIL.
 
-RUN/S CMD &KEY ON-ERROR TIME SHOW HOST
+
+* `RUN/S CMD &KEY ON-ERROR TIME SHOW HOST`
+
   RUN/S is a shorthand for RUN with :OUTPUT bound to :STRING,
   returning as a string what the inferior command sent to its standard output.
 
-RUN/SS CMD &KEY ON-ERROR TIME SHOW HOST
+* `RUN/SS CMD &KEY ON-ERROR TIME SHOW HOST`
+
   RUN/S is a shorthand for RUN :OUTPUT :STRING/STRIPPED,
   just like a shell's `cmd` or $(cmd) would do.
 
-RUN/INTERACTIVE CMD &KEY ON-ERROR TIME SHOW HOST
+
+* `RUN/INTERACTIVE CMD &KEY ON-ERROR TIME SHOW HOST`
+
   RUN/INTERACTIVE is a shorthand for RUN with :INPUT :OUTPUT :ERROR-OUTPUT
-  all boud to :INTERACTIVE, so you may run commands that interact with users,
+  all bound to :INTERACTIVE, so you may run commands that interact with users,
   inheritting the stdin, stdout and stderr of the current process.
+  RUN/I is a shorthand alias for RUN/INTERACTIVE
+
+* `RUN/LINES CMD &KEY ON-ERROR TIME SHOW HOST`
 
-RUN/LINES CMD &KEY ON-ERROR TIME SHOW HOST
   run/lines is a shorthand for RUN :OUTPUT :LINES,
   returning as a list of one string per line (stripped of line-ending)
   what the inferior command sent to its standard output.
 
-*BACKEND*
+* `*BACKEND*`
+
   a variable to choose between backends. Currently, only supported are
   :AUTO (the default, using asdf-driver:run-program, and
   spawning a shell unless it's a simple process), and
   :SBCL (only available on #+(and sbcl sb-thread unix),
   doesn't need a shell but has some limitations such as
-  only supporting redirection of stdin, stdout, stderr).
+  only supporting redirection of stdin, stdout, stderr),
+  and is not recommended (and not actively supported at the moment).
 
 
-==== THE PROCESS-SPEC MINI-LANGUAGE ====
+The PROCESS-SPEC mini-language
+------------------------------
 
 This library offers a SEXP syntax to specify processes
 and pipelines of processes in the manner of Unix shells,
@@ -167,6 +188,7 @@ depending on its capabilities and on the complexity of the pipeline.
 
 SEXP mini-language
 
+```
 ;; A process is a pipe or a command
 process := pipe | or | and | progn | fork | command
 
@@ -207,6 +229,7 @@ redirection := (
  <& fd fd | >& fd fd | ;; redirect fds: the left one is the new number, the right one the old number.
  >& pn | >&! | ;; redirect both fd 1 and 2 to pathname (respectively, clobbering)
  >>& pn | >>&! ) ;; redirect both fd 1 and 2 to append to pathname (respectively, clobbering)
+```
 
 Note that these are all exported symbols from the INFERIOR-SHELL package,
 except that a few of them are also inherited from COMMON-LISP: < > -
@@ -221,9 +244,10 @@ in this context, a string represents itself (assuming it's already a printed pro
 and a cons is a specification in the minilanguage to be parsed with parse-process-spec first.
 
 
-==== TO DO ====
+TO DO
+-----
 
-Document it.
+Better document it.
 
 Have a complementary inferior-shell-watcher library that uses iolib to spawn
 pipes locally, and watch the subprocesses as part of the iolib event loop.
-- 
GitLab