README.org: Clarify `free software' with a link to the FSF.

[runlisp] / README.org

diff --git a/README.org b/README.org
index b59221a2d9d8dc8bc955daa076e04acd69a35c8f..c4aad72df21284b803a9a8c71418574c925ac8f5 100644 (file)
--- a/README.org
+++ b/README.org
@@ -3,6 +3,7 @@
 #+AUTHOR: Mark Wooding
 #+LaTeX_CLASS: strayman
 #+LaTeX_HEADER: \usepackage{tikz, gnuplot-lua-tikz}
 #+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 ~#!~
 #+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.
 
 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
 
 
 * Writing scripts in Common Lisp


@@ -68,6 +70,13 @@ in the ~-L~ option, separated by commas:
 :                          #-(or sbcl ccl) "an unexpected"
 :                          " Common Lisp!~%"))
 
 :                          #-(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
 ** Embedded options
 
 If your script requires features of particular Lisp implementations


@@ -233,8 +242,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.
 
     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.
 
 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 +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
 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
 
 When deciding which Lisp implementation to use, ~runlisp~ works as
 follows.  It builds a list of /acceptable/ Lisp implementations from the


@@ -304,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.)
 
 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]
 : 
 
 : [sbcl]
 :