--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for `runlisp' configuration files
+.\"
+.\" (c) 2020 Mark Wooding
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
+.\"
+.\" Runlisp is free software: you can redistribute it and/or modify it
+.\" under the terms of the GNU General Public License as published by the
+.\" Free Software Foundation; either version 3 of the License, or (at your
+.\" option) any later version.
+.\"
+.\" Runlisp is distributed in the hope that it will be useful, but WITHOUT
+.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+.\" for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Runlisp. If not, see <https://www.gnu.org/licenses/>.
+.
+.ie t \{\
+. ds o \(bu
+. if \n(.g \{\
+. fam P
+. ev an-1
+. fam P
+. ev
+. \}
+.\}
+.el \{\
+. ds o o
+.\}
+.
+.de hP
+.IP
+\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
+..
+.ds , \h'.16667m'
+.
+.\"--------------------------------------------------------------------------
+.TH runlisp.conf 5 "27 August 2020" "Mark Wooding"
+.SH NAME
+runlisp.conf \- configuration files for runlisp
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+.SS "General syntax"
+In summary,
+a configuration file is structured as a collection of assignments
+.I variable
+.B =
+.IR value ,
+gathered into named sections by header lines
+.BI [ section ]\fR.
+.PP
+Comments are indicated by a semicolon
+.RB ` ; '
+in the leftmost column,
+and extend to the end of the line;
+comments and lines consisting only of whiteapace are ignored
+and have no effect whatever.
+Semicolons not in the first column do
+.I not
+introduce comments,
+and have no special meaning.
+.PP
+A
+.I name
+is a non-empty sequence of ASCII alphanumeric characters,
+or the special constituent characters
+.RB ` \- ',
+.RB ` _ ',
+.RB ` . ',
+.RB ` / ',
+.RB ` * ',
+.RB ` + ',
+.RB ` *% ',
+or
+.RB ` @ '.
+For example,
+.RB ` foo ',
+.RB ` 12345 ',
+.RB ` \-2.718 ',
+.RB ` 113/355 ',
+.RB ` image-dir ',
+.RB ` @%IMAGEDIR ',
+and
+.RB ` *organa-solo* '
+are all names, but
+.RB ` foo:bar '
+.RB ` happy? '
+and
+.RB ` $3.95 '
+are not.
+Names beginning with
+.RB ` @ '
+are reserved for use by the
+.B runlisp
+programs;
+names beginning with
+.RB ` % '
+or
+.RB ` @% '
+are by convention private.
+.PP
+A
+.I section header
+is a line of the form
+.IP
+.BI [ section ]
+.PP
+where
+.I section
+is a name, as defined above.
+There may be whitespace before and after the
+.I name
+or after the
+.RB ` ] '.
+Section headers need not have distinct names.
+Subsequent assignments are applied to the section called
+.IR name ,
+up until the next section header, or the end of the file.
+Assignments prior to the first section header in a file
+are applied to the
+.B @CONFIG
+section.
+.PP
+An
+.I assignment
+begins with a line of the form
+.IP
+.I variable
+.B =
+.I rest
+.PP
+where
+.I variable
+is a name, as defined above,
+and it includes all subsequent
+(non-empty, non-comment)
+lines up to, but not including,
+the next line which does
+.I not
+begin with whitespace or a semicolon,
+or the end of the input file.
+There may be space before or after the
+.RB ` = '.
+The
+.I value
+assigned consists of the text of the initial line following the
+.RB ` = '
+character
+(shown as
+.I rest
+above),
+together with the contents of the subsequent lines;
+initial and trailing whitespace is removed from each piece,
+and the (nonempty) pieces are joined,
+separated by single spaces.
+We say that a assignment
+assigns a value to the variable
+in some section \(en
+namely, the section in which the assignment is applied.
+.PP
+For example,
+consider the following file.
+.IP
+.ft B
+.nf
+long =
+ one
+
+ two
+; this line is a comment
+ ; not a comment
+ three
+
+short = just a quick note
+.fi
+.ft P
+.PP
+Then
+.B long
+is assigned the value
+.RB ` "one two ; not a comment three" ',
+and
+.B short is assigned
+.RB ` "just a quick note" '.
+.PP
+The assignments applied to a section
+need not have distinct variable names.
+Only the last assignment to a particular variable name in a section is
+.IR effective ;
+the earlier assignments are simply ignored.
+If an effective assignment assigns a value to a variable in a section,
+we say that the variable is
+.I set
+to that value in the section.
+.
+.SS "Lookup and inheritance"
+A section may have zero or more
+.I parent
+sections.
+.PP
+The
+.BR @BUILTIN ,
+.BR @CONFIG ,
+and
+.B @ENV
+sections have no parents.
+The
+.B @CONFIG
+section has one parent, namely
+.BR @BUILTIN .
+.PP
+If the variable
+.B @parents
+is set in a section other than one of those named above,
+then it must consist of a space- or comma-separated list
+of names,
+which name the section's parents.
+Currently, the parents need not be distinct,
+though duplicates have no effect other than slowing down lookup.
+The order in which parents are listed is not significant.
+If
+.B @parents
+is not set in a section other than one of those named above,
+then by default it has one parent, namely
+.BR @COMMON .
+.PP
+It is currently possible to build a cyclic structure of parent links.
+This is not recommended.
+If lookup (explained below) detects a cycle
+then it will report a fatal error,
+but cycles may exist without being detected.
+.PP
+A variable is
+.I "looked up"
+in a section as follows.
+.hP 1.
+If there is an effective assignment
+of a value to that variable in the section
+then lookup finds that assignment.
+.hP 2.
+If the section has no parents,
+then lookup fails.
+.hP 3.
+Otherwise, the variable is looked up in each of the section's parents.
+If none of these lookups succeeds, then the lookup fails.
+If all of the successful lookups found the
+.I "same assignment"
+(not just the same value!)
+then lookup finds that assignment.
+Otherwise, the lookup reports an error.
+.
+.SS "Expansion and word-splitting"
+A value can be
+.I expanded
+relative to some home section,
+and optionally split into words.
+.PP
+Not all values are
+.IR expandable .
+Values set by assignments in a configuration file are always expandable.
+Values set on the command line \(en in
+.B \-o
+options \(en are not expandable.
+Values in the
+.B @ENV
+section from environment variables (see below) are not expandable.
+Some values set in the
+.B @BUILTIN
+section are expandable and some are not.
+Applying expansion to a value that is not expandable
+simply results in that same value, unchanged.
+.PP
+Applying expansion to an expandable value
+produces a result string as follows.
+The value is scanned from start to end.
+.hP \*o
+A backslash
+.RB ` \e '
+is discarded, but the immediately following character
+is copied to the output without further inspection.
+.hP \*o
+A
+.I variable substitution
+takes the form
+.BR ${ [ \c
+.IB sect : \c
+.RI ] var \c
+.RB [ | \c
+.IR filter ]... \c
+.RB [ ? \c
+.IR alt ] \c
+.BR } .
+A variable named
+.I var
+is looked up in the section named
+.IR sect ,
+or, if omitted, in the home section.
+If the lookup succeeds,
+then the value is expanded,
+processed by the
+.IR filter s
+(explained below),
+and appended to the output.
+If the lookup failed,
+and
+.BI ? alt
+is present,
+then
+.I alt
+is expanded and appended to the output.
+Otherwise,
+if the lookup fails and there is no
+.I alt
+text, then an error is reported.
+.IP
+A filter
+.B u
+causes the expanded value to be converted to uppercase;
+similarly,
+.B l
+causes the expanded value to be converted to lowercase.
+A filter
+.B q
+causes a backslash to be inserted before each
+backslash or double-quote character in the expanded value,
+so that this can be used as part of a quoted Common Lisp string.
+.hP \*o
+A
+.I conditional
+takes the form
+.BR $? [ \c
+.IB sect : \c
+.RI ] var \c
+.BI { conseq \c
+.RB [ | \c
+.IR alt ] \c
+.BR } .
+A variable named
+.I var
+is looked up in the section named
+.IR sect ,
+or, if omitted, in the home section.
+If the lookup succeeds, then
+.I conseq
+is expanded and appended to the output;
+otherwise, if
+.I alt
+is present, then it is expanded and appended to the output;
+otherwise, nothing happens.
+.hP \*o
+A dollar sign which doesn't introduce one of the forms above
+is invalid, and a fatal error is reported.
+.hP \*o
+Any other characters are simply appended to the output.
+.PP
+Word-splitting is similar but more complex.
+The result is not a string, but a sequence of strings.
+At any given point in this procedure,
+there may be a partially constructed word,
+or there might not.
+.hP \*o
+Outside of quotes (see below),
+whitespace serves to separate words.
+When a whitespace character is encountered,
+if there is a word under construction,
+then it is finished and added to the output list;
+otherwise it is simply ignored.
+.hP \*o
+If a backslash is encountered,
+then a word is started if there is none currently under construction,
+and the character following the backslash is added to the current word.
+.hP \*o
+If a single-quote character
+.RB ` ' '
+is encountered,
+then a word is started if there is none currently under construction,
+and
+.I all
+characters up to the next single quote
+are added to the current word.
+This includes double quotes, dollar signs, and backslashes.
+(Neither of the two single quotes is appended to the current word.)
+.hP \*o
+If a double-quote character
+.RB ` """" '
+is encountered,
+then a word is started if there is none currently under construction.
+Until the next double quote is encountered,
+whitespace and single quotes treated literally,
+and simply added to the current word;
+backslashes can be used to escape characters,
+such as double quotes,
+as usual.
+.hP \*o
+If a
+.BR $ -expansion
+\(en a variable substitution or conditional (as described above) \(en
+is encountered
+and there is a current word under construction,
+then the result of the
+.BR $ -expansion
+is appended to the current word.
+If there is no current word,
+then the variable value, or consequent or alternative text,
+is subjected to word splitting in addition to expansion,
+and the resulting words appended to the output sequence.
+.hP \*o
+If any other character is encountered,
+then a word is started if there is none currently under construction,
+and the character is appended to the current word.
+.PP
+One case which deserves attention:
+if a
+.BR $ -expansion
+is encountered outside of a word,
+so that the result is subject to word splitting,
+then an error is reported if a new word is started
+without there being whitespace between the closing brace of the
+.B $ -expansion
+and the character which started the new word.
+For example,
+.IP
+.B "bad = one ${x}two"
+.PP
+would be invalid in a word-splitting context.
+.
+.SS "Predefined variables in @BUILTIN"
+The
+.B @BULITIN
+Section has no parents.
+You should not override its settings in configuration files.
+it holds a number of variables set by the
+.B runlisp
+programs.
+.TP
+.B @data-dir
+The directory in which
+.BR runlisp 's
+auxiliary data files and scripts are located.
+This is determined by the
+.B RUNLISP_DATADIR
+environment variable,
+the
+.B data-dir
+variable in the
+.B @CONFIG
+section,
+or a value determined at compile time.
+.TP
+.B @ecl-opt
+The preferred option prefix for ECL, either
+.RB ` \- '
+or
+.RB ` \-\- '.
+(For some reason,
+the ECL developers are changing
+the way ECL recognizes command-line options,
+because they think that the minor aesthetic improvement
+is worth breaking everyone's scripts.)
+This is determined by the
+.B ecl-opt
+variable in the
+.B @CONFIG
+section,
+or a value determined at compile time.
+.TP
+.B @image-dir
+The directory in which
+.B runlisp
+looks for, and
+.B dump-runlisp-image
+stores, custom Lisp images.
+This is determined by the
+.B RUNLISP_IMAGEDIR
+environment variable,
+the
+.B image-dir
+variable in the
+.B @CONFIG
+section,
+or a value determined at compile time.
+.TP
+.B @image-new
+Set by
+.BR dump-runlisp-image (1)
+to the filename that a
+.B dump-image
+command should create.
+.RB ( dump-runlisp-image
+will rename the image into place itself,
+if the command completes successfully.)
+.TP
+.B @image-out
+Set by
+.BR dump-runlisp-image (1)
+to the filename of the intended output image.
+(Don't use this in
+.B dump-image
+commands: use
+.B @image-new
+instread.)
+.TP
+.B @script
+Set by
+.BR runlisp (1)
+to the name of the script being invoked.
+.TP
+.B @tmp-dir
+Set by
+.BR dump-runlisp-image (1)
+to be the name of a directory in which a
+.B dump-image
+command can put temporary files.
+.
+.SS "Other special variables"
+In every section, the section's name
+is automatically assigned to the variable
+.BR @name .
+This variable
+.I can
+be overridden by an explicit assignment,
+but this is not recommended.
+.
+.\"--------------------------------------------------------------------------
+.
+.SH BUGS
+.hP \*o
+.
+.SH SEE ALSO
+.BR dump-runlisp-image (1),
+.BR query-runlisp-config (1),
+.BR runlisp (1).
+.
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / runlisp / blobdiff