X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/runlisp/blobdiff_plain/ace01e7181b7882e3039702a251ef97c7a87dcaa..5910232a336e0fa2c32bb1a00c8b69e54995d863:/README.org

diff --git a/README.org b/README.org
index f5a95da..62f5216 100644
--- a/README.org
+++ b/README.org
@@ -3,6 +3,7 @@
 #+AUTHOR: Mark Wooding
 #+LaTeX_CLASS: strayman
 #+LaTeX_HEADER: \usepackage{tikz, gnuplot-lua-tikz}
+#+LaTeX_HEADER: \DeclareUnicodeCharacter{200B}{}
 #+EXPORT_FILE_NAME: doc/README.pdf
 
 ~runlisp~ is a small C program intended to be run from a script ~#!~
@@ -24,7 +25,8 @@ configuration file.  Of course, there's a benefit to having a collection
 of high-quality configuration runes curated centrally, so I'm happy to
 accept submissions in support of any free[fn:free] Lisp implementations.
 
-[fn:free] Here I mean free as in freedom.
+[fn:free] Here I mean `free' as in freedom: see
+https://www.fsf.org/about/what-is-free-software.
 
 
 * Writing scripts in Common Lisp
@@ -68,6 +70,13 @@ in the ~-L~ option, separated by commas:
 :                          #-(or sbcl ccl) "an unexpected"
 :                          " Common Lisp!~%"))
 
+It is not an error to include the name of an unrecognized Lisp system in
+the ~-L~ option: such names are simply ignored.  This allows a script to
+declare support for unusual or locally installed Lisp systems without
+compromising its portability to sites where such systems are unknown, or
+which are still running older versions of ~runlisp~ which haven't been
+updated with the necessary configuration for those systems.
+
 ** Embedded options
 
 If your script requires features of particular Lisp implementations
@@ -113,7 +122,7 @@ For example:
 
   + The prevailing Unix standard input, output, and error files are
     available through the Lisp ~*standard-input*~, ~*standard-output*~,
-    and ~*error-ouptut*~ streams, respectively.  (This is, alas, not a
+    and ~*error-output*~ streams, respectively.  (This is, alas, not a
     foregone conclusion.)
 
   + The keyword ~:runlisp-script~ is added to the ~*features*~ list.
@@ -151,24 +160,32 @@ command-line interface for evaluating Lisp forms.  For example:
 : 3
 
 If your build script needs to get information out of Lisp, then wrapping
-~format~, or even ~prin1~, around forms is annoying; so ~runlisp~ has a
+~format~, or even ~princ~, around forms is annoying; so ~runlisp~ has a
 ~-p~ option which prints the values of the forms it evaluates.
 
 : $ runlisp -e '(+ 1 2)'
 : 3
 
-If a form produces multiple values, then ~-p~ will print all of them
-separated by spaces, on a single line:
+If a form produces multiple values, then ~-p~ will print all of them, as
+if by ~princ~, separated by spaces, on a single line:
 
 : $ runlisp -p '(floor 5 2)'
 : 2 1
 
+There's also a ~-d~ option, which does the same thing as ~-p~, only it
+prints values as if by ~prin1~.  For example,
+
+: $ runlisp -p '"Hello, world!"'
+: Hello, world!
+: $ runlisp -d '"Hello, world!"'
+: "Hello, world!"
+
 In addition to evaluating forms with ~-e~, and printing their values
-with ~-p~, you can also load a file of Lisp code using ~-l~.
+with ~-d~ and ~-p~, you can also load a file of Lisp code using ~-l~.
 
 When ~runlisp~ is acting on ~-e~, ~-p~, and/or ~-l~ options, it's said
 to be running in /eval/ mode, rather than its usual /script/ mode.  In
-script mode, it /doesn't/ set ~:runlisp-script~ in ~*features*~.
+eval mode, it /doesn't/ set ~:runlisp-script~ in ~*features*~.
 
 You can still insist that ~runlisp~ use a particular Lisp
 implementation, or one of a subset of implementations, using the ~-L~
@@ -209,7 +226,7 @@ The ~runlisp~ program looks for configuration in a number of places.
     All of the files in this directory named ~SOMETHING.conf~ are read,
     in increasing lexicographical order by name.  The package comes with
     a file ~0base.conf~ intended to be read first, so that it can be
-    overridden if necessar.  This sets up basic definitions, and defines
+    overridden if necessary.  This sets up basic definitions, and defines
     the necessary runes for those Lisp implementations which are
     supported `out of the box'.  New Lisp packages might come with
     additional files to drop into this directory.
@@ -225,14 +242,25 @@ The ~runlisp~ program looks for configuration in a number of places.
     directories to add support for privately installed Lisp systems, or
     to override settings made by earlier configuration files.
 
-The configuration syntax is complicated, and explained in detail in the
-*runlisp.conf* manpage.
+Configuration files generally look like =.ini=-style files.  A line
+beginning with a semicolon ~;~ is a comment and is ignored.  Most lines
+are assignments, which look like
+#+BEGIN_QUOTE
+/name/ ~=~ /value/
+#+END_QUOTE
+and assignments are split into sections by section headers in square
+brackets:
+#+BEGIN_QUOTE
+~[~\relax{}/section/\relax{}~]~
+#+END_QUOTE
+The details of the configuration syntax are complicated, and explained
+in the *runlisp.conf* manpage.
 
 Configuration options can also be set on the command line, though the
 effects are subtly different.  Again, see the manual pages for details.
 
 [fn:xdg-config] More properly, in ~$XDG_CONFIG_HOME/runlisp.conf~, if
-you set that.
+you set that variable.
 
 
 ** Deciding which Lisp implementation to use
@@ -241,7 +269,12 @@ The ~prefer~ option specifies a /preference list/ of Lisp
 implementations.  The value is a list of Lisp implementation names, as
 you'd give to ~-L~, separated by commas and/or spaces.  If the
 environment variable ~RUNLISP_PREFER~ is set, then this overrides any
-value found in the configuration files.
+value found in the configuration files.  So your ~$HOME/.runlisp.conf~
+file might look like this:
+
+: ;;; -*-conf-*-
+:
+: prefer = sbcl, clisp
 
 When deciding which Lisp implementation to use, ~runlisp~ works as
 follows.  It builds a list of /acceptable/ Lisp implementations from the
@@ -296,7 +329,9 @@ Lisp.  (SBCL's command-line interface is well thought-out, so this is an
 ideal opportunity to explain how ~runlisp~ configuration works, without
 getting bogged down in the details of fighting less amenable Lisps.)
 
-The provided ~0base.conf~ file defines SBCL as follows.
+The provided ~0base.conf~ file used to define SBCL as follows.  (The
+real version now contains a kludge for old versions, which needn't
+concern us here.)
 
 : [sbcl]
 : 
@@ -539,7 +574,7 @@ impossible to access.
 : NIL
 
 As another example, Armed Bear Common Lisp doesn't seem to believe in
-the stderr stream: when it starts up, ~*error-ouptut*~ is bound to the
+the stderr stream: when it starts up, ~*error-output*~ is bound to the
 standard output, just like ~*standard-output*~.  Also, ~cl-launch~
 loading ASDF causes a huge number of ~style-warning~ messages to be
 written to stdout, making ABCL pretty much useless for writing filter
@@ -588,5 +623,12 @@ supports.  If you want your scripts to be able to run on other Lisps,
 then ~cl-launch~ is the way to do that.  Of course, I welcome patches to
 help ~runlisp~ support other free Lisp implementations.  ~cl-launch~
 also supports proprietary Lisps: I have very little interest in these,
-so if you want to run scripts using Allegro or LispWorks then
-~cl-launch~ is your only choice.
+so if you want to run scripts using Allegro or LispWorks then your only
+options are to maintain your own ~runlisp~ configuration for these
+systems or to use ~cl-launch~.
+
+* COMMENT Emacs cruft
+
+# LocalWords: abcl Almquist argv ATTR Attr BST clisp CLisp's Clozure CMU ecl
+# LocalWords: env fn ini interp launchrc lua nbsp noinform precompiled prin
+# LocalWords: princ sb SBCL's sed SYSCONFDIR sysinit TBLFM tbp tikz xdg XPS