X-Git-Url: https://git.distorted.org.uk/~mdw/sw-tools/blobdiff_plain/4216aeb54f91dd6bb717a524528e3d7d2b221716..e55daacc8888ea40715a620cf21bef29583a670f:/sw-env.5

diff --git a/sw-env.5 b/sw-env.5
index 84a5bca..df62cc1 100644
--- a/sw-env.5
+++ b/sw-env.5
@@ -1,6 +1,6 @@
 .\" -*-nroff-*-
 .\"
-.\" $Id: sw-env.5,v 1.4 2004/04/08 01:52:18 mdw Exp $
+.\" $Id$
 .\"
 .\" Manual page for `sw-env' files
 .\"
@@ -25,3 +25,270 @@
 .\" along with sw-tools; if not, write to the Free Software Foundation,
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 .
+.\" --- Useful macro definitions ---
+.
+.de VS \" Start a sort-of verbatim block
+.sp 1
+.in +5n
+.nf
+.ft B
+..
+.de VE \" Stop a sort-of verbatim block
+.ft R
+.fi
+.in -5n
+.sp 1
+..
+.de hP \" Start an indented paragraph with a bold right-aligned label
+.IP
+\fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
+..
+.\"
+.\" --- Style hacking ---
+.\"
+.ie \n(.g \{\
+.  fam P
+.  ds mw \fR[\f(BImdw\fR]
+.\}
+.el .ds mw \fR[\fBmdw\fR]
+.ie t .ds o \(bu
+.el .ds o o
+.ds sw \fBsw\fP
+.ds se \fBsw\-env\fP
+.
+.\"----- Main manual text ---------------------------------------------------
+.
+.TH sw-env 5 "25 May 1999" sw-tools
+.PD 1
+.
+.\"--------------------------------------------------------------------------
+.
+.SH NAME
+.
+sw\-env \- environment variable assignment files for \*(sw.
+.
+.\"--------------------------------------------------------------------------
+.
+.SH "DESCRIPTION"
+.
+A \*(se file is a sequence of statements.  The following statements are
+supported:
+.sp 1
+.in +5n
+.B :
+.I value
+.RB [ ; ]
+.br
+.B include
+.I value
+.RB [ ; ]
+.br
+.B arch
+.I value
+.B {
+.IR statement ...
+.B }
+.RB [ ; ]
+.br
+.RB [ set ]
+.I name
+.RB [ = ]
+.I value
+.RB [ ; ]
+.br
+.B unset
+.I name
+.RB [ ; ]
+.in -5n
+.sp 1
+Whitespace serves to separate tokens but is otherwise ignored except
+when it occurs quoted within a
+.IR value .
+The file may also contain comments, which begin with a
+.RB ` # '
+character and extend to the end of the line.  The start of a comment
+must appear where a new statement is expected.  Apart from its behaviour
+of terminating comments, newlines behave the same way as other
+whitespace characters.  Keywords are not reserved words.
+.PP
+A
+.I name
+is a sequence of digits, letters and underscores which does not start
+with a digit.
+.PP
+A
+.I value
+may contain any non-null character, although some characters are special
+and must be quoted.  The syntax of
+.IR value s
+is loosely based on the Bourne
+shell, although there are differences and irregularities due to the
+quick and dirty nature of the parser.  The various quoting and
+substitution operations are described below.
+.
+.SS "Statements"
+.
+The statements behave as follows:
+.TP
+.B :
+The following
+.I value
+is read and discarded.  This is not useless: reading a
+.I value
+may cause variables to be assigned as a result of
+`\c
+.BI ${ name = value }\c
+\&' substitutions.
+.TP
+.B include
+A
+.I value
+is read, and further assignments are read from the file so named, if it
+exists.  Conventionally, the last statement in the global \*(se file is
+.VS
+include ".sw-env";
+.VE
+to read in package-specific settings.
+.TP
+.B arch
+The following
+.I value
+is read.  If it matches the name of the host's architecture, then the
+brace-enclosed statements are executed; otherwise they're ignored.  It's
+possible, though not useful, to nest
+.B arch
+statements.
+.TP
+.B set
+A
+.I name
+and
+.I value
+are read, optionally separated by an
+.RB ` = '
+character.  The variable named is assigned the value, replacing any
+previously assigned value, if any.  The
+.RB ` set '
+keyword is optional.  It's only useful so that you can assign values to
+variables whose names are also statement keywords.
+.TP
+.B unset
+A
+.I name
+is read.  Any value assigned to the variable named is discarded, and the
+variable is forgotten.
+.
+.SS "Value syntax"
+.
+The parser usually reads a
+.I value
+a character by character, until it finds a delimiter.  Delimiter
+characters are
+.RB ` ( ',
+.RB ` ) ',
+.RB ` { ',
+.RB ` } ',
+and
+.RB ` ; ';
+whitespace also acts as a delimiter.  Delimiter characters can only
+appear in a value if quoted.
+.PP
+There are three types of quoting understood by the value reader.  A
+backslash
+.RB (` \e ')
+character causes the following character to be stripped of its special
+meaning.  Hence
+.RB ` \e\e '
+inserts a literal backslash.  Text between single quotes
+.RB ` \' ... \' '
+is read
+entirely as-is, including all whitespace, newlines, backslashes,
+everything.  To include a single quote in a piece of single-quoted text,
+use the sequence
+.RB ` \'\e\'\' ',
+as in the shell.  (This drops out of single-quoting, inserts an escaped
+single quote, and resumes quoting.)  Text between double quotes
+.BR """" ... """"
+is partially quoted: delimiters and whitespace are read as normal
+characters, but substitutions using the
+.RB ` $ '
+and
+.RB ` \` '
+characters are still made, and the backslash retains its behaviour of
+escaping the following character.
+.PP
+Two sorts of substitutions are available in values:
+.I "variable substitution"
+examines a variable and substitutes some text based on its value, and
+.I "command substitution"
+runs a command and substitutes its output.
+.PP
+The simplest variable substitution takes the form
+.RB ` $\c
+.IR name ':
+this is replaced by the value of the variable called
+.IR name ,
+or the empty string if there is no such variable defined.  The name may
+be enclosed in braces should it be necessary to clearly disambiguate the
+end of the name.
+.PP
+More complex variable substitutions are permitted:
+.TP
+.BI ${ name \- text }
+Expands to the value of the variable called
+.I name
+if it's defined, or
+.I text
+if not.
+.TP
+.BI ${ name + text }
+Expands to
+.I text
+if there is a variable called
+.I name
+defined, or nothing.
+.TP
+.BI ${ name = text }
+If there is no variable called
+.I name
+then create one with the value
+.IR text ;
+then expands to the variable's value.
+.PP
+In each of the above, prefixing the operator character
+.RB ` \- ',
+.RB ` + '
+or
+.RB ` = '
+with a colon
+.RB (` : ')
+changes the variable existence test, such that it will believe that a
+variable whose value is the empty string is not defined.  Each
+.I text
+part in the above forms is syntactically a
+.IR value ,
+and may itself contain quoting and substitutions.  It may also contain
+unescaped whitespace.
+.PP
+There are two forms for command substitution: the backtick form, where a
+command is enclosed in backquotes
+.RB ` \` ... \` ';
+and the parenthesized form
+.RB ` $( ... ) '.
+The only difference between these two forms is syntactic: it's easy to
+make the parenthesized version nest, although that's not actually very
+useful.  The text between the backquotes or parentheses is broken into
+words and executed as a command.  It is not passed through the shell:
+the author suspects that this would be too confusing.  The standard
+output of the command, with trailing newlines (but not internal or
+leading newlines) removed, is the result of the substitution.
+.
+.\"--------------------------------------------------------------------------
+.
+.SH "AUTHOR"
+.
+The \*(sw program, and this manual, are \*(mw productions, in association
+with the European Bioinformatics Institute.  They were written by Mark
+Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
+.
+.\"----- That's all, folks --------------------------------------------------