README.org: Use a more principled hack to make emphasis work.

[runlisp] / README.org

diff --git a/README.org b/README.org
index 4a4ee01..821b4c9 100644 (file)
--- a/README.org
+++ b/README.org
@@ -3,6 +3,8 @@
 #+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 ~#!~
 line.  It selects and invokes a Common Lisp implementation, so as to run
 
 ~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~),
   + 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~).
 
   + 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
 : 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~


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


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


@@ -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
 ~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}
 
 : [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~
 
   + 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
     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
 
     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 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 ~\~.
     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, 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
 
 #+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.)
 
 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
 
 
 ** It's inconvenient
 


@@ -562,7 +588,7 @@ scripts.
 level of shell integration for all its supported Lisp implementations.
 In particular:
 
 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.
 
     file descriptors are hooked up to the Lisp ~*standard-input*~,
     ~*standard-output*~, and ~*error-output*~ streams.