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

[runlisp] / README.org

diff --git a/README.org b/README.org
index 59ada8b..821b4c9 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 ~#!~


@@ -15,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~).
 


@@ -151,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~


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


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


@@ -374,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 ~\~.


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