X-Git-Url: https://git.distorted.org.uk/~mdw/sw-tools/blobdiff_plain/c629200be4128053bb2c1e73f1b337cf099c2411..9796a7877cd1e7f6908c678e71b8fea6045ba0e7:/sw-env.5 diff --git a/sw-env.5 b/sw-env.5 index 02a91ff..84a5bca 100644 --- a/sw-env.5 +++ b/sw-env.5 @@ -1,6 +1,6 @@ .\" -*-nroff-*- .\" -.\" $Id: sw-env.5,v 1.3 1999/07/30 18:44:32 mdw Exp $ +.\" $Id: sw-env.5,v 1.4 2004/04/08 01:52:18 mdw Exp $ .\" .\" Manual page for `sw-env' files .\" @@ -25,283 +25,3 @@ .\" along with sw-tools; if not, write to the Free Software Foundation, .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. . -.\"----- Revision history --------------------------------------------------- -.\" -.\" $Log: sw-env.5,v $ -.\" Revision 1.3 1999/07/30 18:44:32 mdw -.\" Improve cross-references and tidy up formatting. -.\" -.\" Revision 1.2 1999/07/16 12:45:37 mdw -.\" Internal formatting improvements. -.\" -.\" Revision 1.1 1999/06/04 13:56:18 mdw -.\" New manual page. -.\" -. -.\" --- 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 . Go and ask him if you have problems. -. -.\"----- That's all, folks --------------------------------------------------