lib.c: Fix some minor commentary typos.

[runlisp] / dump-runlisp-image.1.in

diff --git a/dump-runlisp-image.1.in b/dump-runlisp-image.1.in
index 26d58f3..46c58c1 100644 (file)
--- a/dump-runlisp-image.1.in
+++ b/dump-runlisp-image.1.in
@@ -39,7 +39,7 @@
 .IP
 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
 ..
-.ds , \h'.16667m'
+.ds .. \&.\|.\|.
 .
 .\"--------------------------------------------------------------------------
 .TH dump-runlisp-image 1 "12 August 2020" "Mark Wooding"
@@ -55,7 +55,7 @@ dump-runlisp-image \- dump Lisp images for faster script execution
 .RB [ \-O
 .IR output ]
 .br
-       \&
+       \c
 .RB [ \-c
 .IR conf ]
 .RB [ \-o
@@ -66,14 +66,14 @@ dump-runlisp-image \- dump Lisp images for faster script execution
 .RB [ \-j
 .IR njobs ]
 .RI [ lisp
-\&...]
+\*(..]
 .
 .\"--------------------------------------------------------------------------
 .SH DESCRIPTION
 .
 The
 .B dump-runlisp-image
-program builds custom images for use by
+program builds and manages custom images for use by
 .BR runlisp (1).
 For many Lisp implementation,
 a custom image,
@@ -81,6 +81,20 @@ with ASDF already loaded,
 can start scripts much more quickly
 than the `vanilla' images installed by default.
 The downside is that custom images may be rather large.
+.PP
+There are actually
+.I two
+filenames for each Lisp image:
+the well-known one that
+.BR runlisp (1)
+uses to run scripts is a symbolic link to the other,
+the actual image file,
+whose name contains an ugly hexadecimal lump
+which identifies the versions of the Lisp code dumped in the image file.
+The
+.B dump-runlisp-image
+program uses this hash to determine whether
+the current image is up-to-date or needs replacing.
 .
 .SS "Options"
 The following options are accepted on the command line.
@@ -103,27 +117,6 @@ to standard output
 and immediately exit with status 0.
 .
 .TP
-.BR "\-R" ", " "\-\-remove-other"
-After processing the selected Lisp implementations,
-delete all of the image files corresponding to other Lisps
-defined in the configuration.
-Negate with
-.B +R
-or
-.BR \-\-no-remove-other .
-.
-.TP
-.BR "\-U" ", " "\-\-remove-unknown"
-After processing the selected Lisp implementations,
-delete all of the files in the image directory which
-.I aren't
-image files of a configured Lisp implementation.
-Negate with
-.B +U
-or
-.BR \-\-no-remove-unknown .
-.
-.TP
 .BI "\-O" "\fR, " "\-\-output=" output
 If
 .I output
@@ -149,6 +142,27 @@ run
 to see the default setting.
 .
 .TP
+.BR "\-R" ", " "\-\-remove-other"
+After processing the selected Lisp implementations,
+delete all of the image files corresponding to other Lisps
+defined in the configuration.
+Negate with
+.B +R
+or
+.BR \-\-no-remove-other .
+.
+.TP
+.BR "\-U" ", " "\-\-remove-unknown"
+After processing the selected Lisp implementations,
+delete all of the files in the image directory which
+.I aren't
+image files of a configured Lisp implementation.
+Negate with
+.B +U
+or
+.BR \-\-no-remove-unknown .
+.
+.TP
 .BR "\-a" ", " "\-\-all-configured"
 Select all configured Lisp implementations.
 You must either list Lisp implementations explicitly on the command line
@@ -230,6 +244,21 @@ or
 .BR "\-\-no-dry-run" .
 .
 .TP
+.BI "\-o" "\fR, " "\-\-set-option=\fR[" sect "\fR]\fB:" var = value
+Assign
+.I value
+to the variable
+.I var
+in configuration section
+.IR sect ,
+or
+.B @CONFIG
+if no section is specified.
+The value is unexpandable,
+and overrides any similarly named setting
+from the configuration file(s).
+.
+.TP
 .BR "\-q" ", " "\-\-quiet"
 Don't print warning messages.
 This option may be repeated:
@@ -305,7 +334,40 @@ option is set,
 then only those Lisp implementations which are actually installed
 are selected.
 .PP
+If necessary
+(see below),
+.B dump-runlisp-image
+invokes each selected Lisp in order to determine a
+.IR "version hash" .
+For each selected Lisp system,
+it constructs a command line,
+in the manner of
+.BR runlisp (1),
+to evaluate the expression resulting from expanding the
+.B lisp-version
+setting in the Lisp system's configuration section.
+It hashes the result,
+using a collision-resistant hash function
+(currently SHA256),
+to produce a string of hexadecimal digits which represents
+the versions of the various pieces of Lisp code which
+.I should
+be in the dumped image.
+The standard setting for
+.B lisp-version
+includes the Lisp implementation version string
+and the version of ASDF currently installed.
+(This step is skipped
+if it's not necessary to determine the Lisp system versions.
+In practice, this happens when the
+.RB ` \-r ',
+.RB ` \-R '
+and
+.RB ` \-U '
+options are all set.)
+.PP
 Having established the selected Lisps,
+and their version hashes,
 .B dump-runlisp-image
 proceeds to act on them:
 in the absence of the