runlisp-base.conf: Etch SBCL's idea of where its `home' is.
[runlisp] / README.org
index b59221a..29fb37d 100644 (file)
@@ -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 ~#!~
@@ -68,6 +69,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
@@ -233,8 +241,19 @@ 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.
+But 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.
@@ -249,7 +268,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
@@ -304,7 +328,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]
 :