debian/copyright: Fix and extend based on CFD research.

[runlisp] / README.org

diff --git a/README.org b/README.org
index f5a95dac2a0e0001c7e313b387f690171565fa5f..62f521636b5d25e35ef263cafaf60a5dab1fce29 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


@@ -113,7 +122,7 @@ For example:
 
   + The prevailing Unix standard input, output, and error files are
     available through the Lisp ~*standard-input*~, ~*standard-output*~,
 
   + The prevailing Unix standard input, output, and error files are
     available through the Lisp ~*standard-input*~, ~*standard-output*~,

-    and ~*error-ouptut*~ streams, respectively.  (This is, alas, not a
+    and ~*error-output*~ streams, respectively.  (This is, alas, not a

     foregone conclusion.)
 
   + The keyword ~:runlisp-script~ is added to the ~*features*~ list.
     foregone conclusion.)
 
   + The keyword ~:runlisp-script~ is added to the ~*features*~ list.


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


@@ -209,7 +226,7 @@ The ~runlisp~ program looks for configuration in a number of places.
     All of the files in this directory named ~SOMETHING.conf~ are read,
     in increasing lexicographical order by name.  The package comes with
     a file ~0base.conf~ intended to be read first, so that it can be
     All of the files in this directory named ~SOMETHING.conf~ are read,
     in increasing lexicographical order by name.  The package comes with
     a file ~0base.conf~ intended to be read first, so that it can be

-    overridden if necessar.  This sets up basic definitions, and defines
+    overridden if necessary.  This sets up basic definitions, and defines

     the necessary runes for those Lisp implementations which are
     supported `out of the box'.  New Lisp packages might come with
     additional files to drop into this directory.
     the necessary runes for those Lisp implementations which are
     supported `out of the box'.  New Lisp packages might come with
     additional files to drop into this directory.


@@ -225,14 +242,25 @@ 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.
+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.
 
 [fn:xdg-config] More properly, in ~$XDG_CONFIG_HOME/runlisp.conf~, if
 
 Configuration options can also be set on the command line, though the
 effects are subtly different.  Again, see the manual pages for details.
 
 [fn:xdg-config] More properly, in ~$XDG_CONFIG_HOME/runlisp.conf~, if

-you set that.
+you set that variable.

 
 
 ** Deciding which Lisp implementation to use
 
 
 ** Deciding which Lisp implementation to use


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


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


@@ -539,7 +574,7 @@ impossible to access.
 : NIL
 
 As another example, Armed Bear Common Lisp doesn't seem to believe in
 : NIL
 
 As another example, Armed Bear Common Lisp doesn't seem to believe in

-the stderr stream: when it starts up, ~*error-ouptut*~ is bound to the
+the stderr stream: when it starts up, ~*error-output*~ is bound to the

 standard output, just like ~*standard-output*~.  Also, ~cl-launch~
 loading ASDF causes a huge number of ~style-warning~ messages to be
 written to stdout, making ABCL pretty much useless for writing filter
 standard output, just like ~*standard-output*~.  Also, ~cl-launch~
 loading ASDF causes a huge number of ~style-warning~ messages to be
 written to stdout, making ABCL pretty much useless for writing filter


@@ -588,5 +623,12 @@ supports.  If you want your scripts to be able to run on other Lisps,
 then ~cl-launch~ is the way to do that.  Of course, I welcome patches to
 help ~runlisp~ support other free Lisp implementations.  ~cl-launch~
 also supports proprietary Lisps: I have very little interest in these,
 then ~cl-launch~ is the way to do that.  Of course, I welcome patches to
 help ~runlisp~ support other free Lisp implementations.  ~cl-launch~
 also supports proprietary Lisps: I have very little interest in these,

-so if you want to run scripts using Allegro or LispWorks then
-~cl-launch~ is your only choice.
+so if you want to run scripts using Allegro or LispWorks then your only
+options are to maintain your own ~runlisp~ configuration for these
+systems or to use ~cl-launch~.
+
+* COMMENT Emacs cruft
+
+# LocalWords: abcl Almquist argv ATTR Attr BST clisp CLisp's Clozure CMU ecl
+# LocalWords: env fn ini interp launchrc lua nbsp noinform precompiled prin
+# LocalWords: princ sb SBCL's sed SYSCONFDIR sysinit TBLFM tbp tikz xdg XPS