+++ /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