tests.at: Use the `@%:@' quadrigraph rather than quoting hacks for `#'.

[runlisp] / README.org

diff --git a/README.org b/README.org
index f5a95da..29fb37d 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 ~#!~


@@ -68,6 +69,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


@@ -151,24 +159,32 @@ command-line interface for evaluating Lisp forms.  For example:
 : 3
 
 If your build script needs to get information out of Lisp, then wrapping
 : 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
 
 ~-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
 
 
 : $ 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
 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
 
 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~
 
 You can still insist that ~runlisp~ use a particular Lisp
 implementation, or one of a subset of implementations, using the ~-L~


@@ -225,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.
 
     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.


@@ -241,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
 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


@@ -296,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.)
 
 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]
 :