.\" $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=\fIlevel\fR ] [ .B \-h | .B \-\-help ] [ .B \-p | .B \-\-list\-paths ] [ .B \-H | .B \-nH ] [ .B \-X | .B \-nX ] [ .B \-P .I word ] [ .B \-\-comment\-input\-start=\fIchar\fR ] [ .B \-\-comment\-input\-end=\fIchar\fR ] [ .B \-\-comment\-output\-start=\fIchar\fR ] [ .B \-\-comment\-output\-end=\fIchar\fR ] [ .B \-\-comment\-input\-style=\fIstyle\fR ] [ .B \-\-comment\-input\-style=\fIstyle\fR ] [ .B \-D .I variable\fR=\fIvalue ] [ .I infile ] [ .I outfile ] .br .ne 5 .SH DESCRIPTION This manual page documents version SPPSYM_RELEASE_ID 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 ADE files are files of \(oqhigher' type with ADE directives hidden inside comments which conform the syntax of that higher type. For example, ADE directives might be hidden inside HTML comments in a .html file. The reason for this is to ensure that an unprocessed file is still valid in the syntax of the \(oqhigher' language. .B Adespp understands how to extract ADE directives from C, nroff, HTML and shell script comments, but there are options to allow the specification of any comment-leader and comment-trailer text in the input. .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. This block comment is delayed until after the first few lines if required. For example, if the first line starts \(oq#!' or \(oq' then the comment block is delayed. This output block is presented as a comment in the \(oqhigher' language. Again, there are options to specify different output languages. .PP .B Adespp identifies directives by looking for the higher language's comment start sequence followed by the text .B spp\fR. This text may be changed with an option. In the following list of valid directives, the comment character shown is a hash: .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 \-\-comment\-input\-end=\fItext\fR This defines the end of a comment in the input stream. It defaults to '' (i.e. nothing). .TP .B \-\-comment\-input\-start=\fItext\fR This defines the start of a comment in the input stream. It .TP .B \-\-comment\-input\-style=\fIstyle\fR This defines the start and end of comments in the input stream. Valid values for .I style are .B html\fR, \fBc\fR, \fBhtml\fR, \fBman\fR. .TP .B \-\-comment\-output\-end=\fItext\fR This defines the end of a comment in the output stream. It defaults to '' (i.e. nothing). .TP .B \-\-comment\-output\-start=\fItext\fR This defines the start of a comment in the output stream. It .TP .B \-\-comment\-output\-style=\fIstyle\fR This defines the start and end of comments in the output stream. Valid values for are the same as for the .B \-\-comment\-input\-style option. .TP .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 25 .B -D \fIvariable\fB=\fIvalue\fR The specified value is assigned to the specified .B SPP variable. .TP .B \-h \fR,\fB \-\-help Displays a brief usage message. .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 \-nX Forces .B adespp to make the output file not executable in a context in which it would normally do so. .TP .B \-p \fR,\fB \-\-list\-paths List the compiled-in paths of various files and directories that .B adespp uses. .TP .B \-P \fIword\fR This changes the word component of the directive leader to .I word\fR. .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 \-X Forces .B adespp to make the output file executable in a context in which it would not normally do so. .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 -nH --comment-input-char '!' $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 .br .ne 5 .SH COPYRIGHT & DISTRIBUTION POLICY Copyright (C) 1997-SPPSYM_RELEASE_YEAR 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.