.\" $HeadURL$ $LastChangedRevision$
.\"
.TH ADESPP 1 "1 January 2003"
.SH NAME
adeapp \- SPP preprocessor
.br
.ne 5
.SH SYNOPSIS
.B adespp
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug
.I level
] [
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
]
[
.B \-H
|
.B \-nH
] [
.B \-X
|
.B \-nX 
] [
.B \-P
.I word
] [
.B \-C
.I char
] [
.B \-D
.I variable\fR=\fIvalue
] [
.I infile
] [
.I outfile
]
.br
.ne 5
.SH DESCRIPTION
This manual page documents version SPPSYM_RELEASEID of 
.B adespp\fR.
.PP 
.B Adespp
is a preprocessor for
.B SPP
files. I.e.
.B SPP 
is a language, and 
.B adespp
is the interpreter of that language that is distributed as part of the 
ADE package (see
.B adeintro\fR(1)).
.PP
Both 
.B SPP 
and 
.B adespp
were developed with scripts in mind. However, the language and
the preprocessor are not designed for programming, but rather for the
preparation of intermediate files or streams, just as is the case for
.B cpp\fR(1)
and
.B m4\fR(1).
.B SPP
is not such a rich language as those that are supported by 
.B cpp\fR(1)
and 
.B m4\fR(1),
but it is far easier to integrate into scripts because its control
directives are not as open to misinterpretation as are those of
.B cpp\fR(1)
and 
.B m4\fR(1).
(Try cpp'ing a Shell script with a lot of comments in it to see the problem.)
.PP
If neither
.I infile 
nor
.I outfile
are specified, standard input and standard output are used. 
If only one of the filenames is specified it is assumed to be the input
file and it must end with the
.B .spp 
suffix in order that the output file can have the same filename stem with
the suffix stripped. The output file will be made executable. 
Either filename can be replaced with
.\" This is a correctly quoted minus sign. It does not look good in X11,
.\" but that is a problem with X11 fonts, not with this code.
.\" see http://www.ffii.org/archive/mails/groff/2001/Dec/0155.html for
.\" details.
\(oq\fB\-\fR',
in which case standard input or standard output will be used as appropriate.
.PP
.B Adespp 
writes a block comment at the top of the output, explaining that the output 
was generated and should therefore not be manually modified. When generating
output which is an executable script, the block comment is delayed until
after the 
\(oq#!'
has been outputted.
.PP
.B Adespp
identifies directives by spotting the left-justified
directive leader which precedes them.
This directive leader is a string consisting of a comment character and 
a further word. By default the directive leader is
.B #spp\fR.
The hash character is used as the default because it is a common comment 
character, which means it is possible to use the same source file on systems 
both with and without 
.B adespp
installed.
.PP
.B Adespp 
understands the following directives:
.TP 25
.B #spp if \fIcommand\fR
.br
.ns
.TP
.I if-clause-text
.br
.ns
.TP
.B #spp else
.br
.ns
.TP
.I else-clause-text
.br
.ns
.TP
.B #spp fi
If the return code of the single Unix
.I command
is zero, then 
.I if-clause-text
is outputted, otherwise the
.I else-clause-text\fR.
This directive can be nested.
.TP
.B #spp define \fIvariable value
The specified value is assigned the specified variable.
.TP 
.B #spp exec \fIcommand
The standard output of the specified command is inserted in the output file.
.TP
.B #spp include \fIfilename
The contents of 
.I filename
are processed immediately. Processing returns to the next line after its completion.
.TP
.B #spp comment \fItext
This line is totally ignored.
.TP
.B #spp debug \fIlevel \fItext
If the debugging or verbose options are used with 
.B adespp,
and 
.I level 
is less than or equal to the level specified on the 
.B adespp
command line, then 
.I text 
is sent to standard error.
.PP
All remaining input is subjected to the substitution of 
.B SPP
variables for their values before being outputted. Note
that substitution also occurs in the parameters to 
.B if\fR, \fBexec\fR and \fBinclude
directives. Note also that subsitution is not recursive;
i.e. the value of a variable cannot be another variable.
.br
.ne 5
.SH CONFIGURATION
None.
.br
.ne 5
.SH OPTIONS
.TP 25
.B \-d \fIlevel\fR,\fB \-\-debug \fIlevel\fR
Determines how verbose
.B adespp
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP
.B \-h \fR,\fB \-\-help
Displays a brief usage message.
.TP
.B \-p \fR,\fB \-\-list\-paths
List the compiled-in paths of various files and directories that
.B adespp
uses.
.TP 
.B \-v \fR,\fB \-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V \fR,\fB \-\-version
Print the program's version number and exit.
.TP
.B \-H
Forces 
.B adespp 
to write a block comment in a context in which it would not normally do so.
.TP
.B \-nH
Forces 
.B adespp
to not write a block comment in a context in which it would normally do so.
.TP
.B \-X
Forces
.B adespp
to make the output file executable in a context in which it would not 
normally do so.
.TP 
.B \-nX
Forces
.B adespp
to make the output file not executable in a context in which it would 
normally do so.
.TP
.B \-C \fIchar\fR
This changes the first character of the directive leader to 
.I char\fR.
.TP
.B \-P \fIword\fR
This changes the word component of the directive leader to
.I word\fR.
.TP
.B -D \fIvariable\fB=\fIvalue\fR
The specified value is assigned to the specified
.B SPP
variable.
.PP
.br
.ne 5
.SH EXIT STATUS
On success
.B adespp
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.TP 
.B PATH
Used by 
.B env\fR(1)
to invoke
.B perl\fR(1), 
and to invoke the commands specified in 
.B if
and
.B exec
directives.
.br
.ne 5
.SH EXAMPLES
Using 
.B adeconf\fR(1)
it is possible to generate a file 
.B paths.spp
which contains site-specific path settings, something like this:
.IP
.nf
.fam C
#spp define SPP\&SYM_BINDIR /usr/local/bin
.\" The variable definition above is expressed like that simply
.\" in order that the files installed in the target man/man*
.\" directory do not contain markers. This is *not* a necessity;
.\" this file is not a .spp file; it is not processed, so if
.\" the variable is here in its normal form it won't be expanded.
.\" But it is nicer to be able to grep through the target
.\" directory and see that there are no markers left unsubstituted;
.\" and having these markers will make me think "Err ... why is
.\" this marker not substituted?" even though it's right that it
.\" is here.
#spp define SPP\&SYM_MANDIR /usr/local/man
#spp define SPP\&SYM_LIBDIR /usr/local/lib
#spp define SPP\&SYM_CFGDIR /etc
.fam T
.fi
.PP
A script source, say go.spp, is then free to not worry about the location of 
various files it needs to run:
.IP
.nf
.fam C
#!SPP\&SYM_SHELL_CMD
#spp include paths.spp
PATH=/bin:/usr/bin
PROGNAME=`basename $0`
MY_CONFIG_FILE=SPP\&SYM_CFGDIR/$PROGNAME.conf
MY_SUPPORT_PROGRAMS_DIR=SPP\&SYM_LIBDIR/$PROGNAME
#
#  The rest of the code, including some to read the config 
#  file, and perhaps call its support programs would be here.
#
.fam T
.fi
.PP
This script could then be preprocessed with the command:
.IP
.nf
.fam C
.B adespp -D SPP\&SYM_SHELL_CMD=/usr/bin/ksh go.spp
.fam T
.fi
.PP
If $HOME/.Xdefaults.spp contained:
.IP
.nf
.fam C
!spp if [ `uname -n` = mickey ]
Xterm.*reverseVideo: true
!spp else
Xterm.*reverseVideo: false
!spp fi
.fam T
.fi
.PP
then the following command could be run from .xsession, or equivalent:
.IP
.nf
.fam C
.B adespp -C ! $HOME/.Xdefaults.spp - | xrdb -merge
.fam T
.fi
.br
.ne 5
.SH CAVEATS
If 
.I command
is required to be more than one Unix command, then embrace it inside the
single command:
.IP
.nf
.fam C
.B sh -c '\fIcommand-one\fB; \fIcommand-two\fB'
.fam T
.br
.ne 5
.SH SEE ALSO
cpp(1), m4(1), perl(1), env(1)
.br
.ne 5
.SH AUTHOR
SPPSYM_AUTHOR_NAME <SPPSYM_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1997-2002 SPPSYM_AUTHOR_NAME
.PP
This program 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 2 of the License, or
(at your option) any later version.
.PP
This program 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.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.