X-Git-Url: https://git.distorted.org.uk/~mdw/runlisp/blobdiff_plain/feb28f7512ebbe85041d2388e5e9db70caf1e2a8..HEAD:/README.org

diff --git a/README.org b/README.org
index 4a4ee01..821b4c9 100644
--- a/README.org
+++ b/README.org
@@ -3,6 +3,8 @@
 #+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 ~#!~
 line.  It selects and invokes a Common Lisp implementation, so as to run
@@ -14,7 +16,7 @@ Currently, the following Lisp implementations are supported:
   + Armed Bear Common Lisp (~abcl~),
   + Clozure Common Lisp (~ccl~),
   + GNU CLisp (~clisp~),
-  + Carnegie--Mellon Univerity Common Lisp (~cmucl~), and
+  + Carnegie--Mellon Univerity Common Lisp (~cmucl~),
   + Embeddable Common Lisp (~ecl~), and
   + Steel Bank Common Lisp (~sbcl~).
 
@@ -150,24 +152,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~
@@ -224,8 +234,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.
@@ -240,7 +261,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
@@ -264,15 +290,14 @@ as possible.  An awkward Lisp will of course cause trouble, but
 ~runlisp~ itself is easy.
 
 As a simple example, let's add support for the 32-bit version of
-Clozure~CL.  The source code for Clozure~CL easily builds both 32- and
-64-bit binaries in either 32- or 64-bit userlands, and one might
-reasonably want to use the 32-bit CCL for some reason.  The following
-configuration stanza is sufficient
+Clozure\nbsp{}CL.  The source code for Clozure\nbsp{}CL easily builds
+both 32- and 64-bit binaries in either 32- or 64-bit userlands, and one
+might reasonably want to use the 32-bit CCL for some reason.  The
+following configuration stanza is sufficient
 
 : [ccl32]
 : @PARENTS = ccl
 : command = ${@ENV:CCL32?ccl32}
-: image-file = ccl32+asdf.image
 
   + The first line heads a configuration section, providing the name
     which will be used for this Lisp implementation, e.g., in ~-L~
@@ -345,8 +370,9 @@ Let's take this in slightly larger pieces.
     we add the tokens ~--core "${image-path}" --eval "${image-restore}"~
     to the SBCL command line; otherwise, we add ~--eval
     "${run-script-prelude}"~.  The ~@IMAGE~ setting is defined by
-    ~runlisp~ only if (a)~a custom image was found in the correct place,
-    and (b)~use of custom images isn't disabled on its command line.
+    ~runlisp~ only if (a)\nbsp{}a custom image was found in the correct
+    place, and (b)\nbsp{}use of custom images isn't disabled on its
+    command line.
 
     The ~${image-path}~ token expands to the full pathname to the custom
     image file; ~image-restore~ is a predefined Lisp expression to be
@@ -373,7 +399,7 @@ Let's take this in slightly larger pieces.
 
     The thing we haven't seen before is ~${@IMAGENEW|q}~.  The
     ~@IMAGENEW~ setting is defined by the ~dump-runlisp-image~ program
-    the name the file in which the new image should be
+    to name the file in which the new image should be
     saved.[fn:image-rename]  The ~|q~ `filter' is new: it means that the
     filename should be escaped suitable for inclusion in a Lisp quoted
     string, by prefixing each ~\~ or ~"~ with a ~\~.
@@ -410,8 +436,8 @@ I timed how long it took to run on all of ~runlisp~'s supported Lisp
 implementations, and compared them to how long ~cl-launch~ took: the
 results are shown in table [[tab:runlisp-vanilla]].  ~runlisp~ is /at least/
 two and half times faster at running this script than ~cl-launch~ on all
-implementations except Clozure CL[fn:slow-ccl], and approaching four and
-a half times faster on SBCL.
+implementations except Clozure\nbsp{}CL[fn:slow-ccl], and approaching
+four and a half times faster on SBCL.
 
 #+CAPTION: ~cl-launch~ vs ~runlisp~ (with vanilla images)
 #+NAME: tab:runlisp-vanilla
@@ -494,8 +520,8 @@ XPS13 laptop running Debian `buster'.  The tools used to make the
 measurements are included in the source distribution, in the ~bench/~
 subdirectory.)
 
-[fn:slow-ccl] I don't know why Clozure CL shows such a small difference
-here.
+[fn:slow-ccl] I don't know why Clozure\nbsp{}CL shows such a small
+difference here.
 
 ** It's inconvenient
 
@@ -562,7 +588,7 @@ scripts.
 level of shell integration for all its supported Lisp implementations.
 In particular:
 
-  + It ensures that the standard Unix `stdin', `stdout', and `stdarr'
+  + It ensures that the standard Unix `stdin', `stdout', and `stderr'
     file descriptors are hooked up to the Lisp ~*standard-input*~,
     ~*standard-output*~, and ~*error-output*~ streams.