### stp-0.5.6 README file

       stp stands for "simple text (pre)processor". It lets you
       conditionally include bits of text, have macros for commonly used
       things, and stuff, thus allowing you to create dynamic text files.
       It's kinda like the pre-processor you have for C/C++ (#define, #ifdef,
       #include etc.).

    Download it from http://www.grundell.u-net.com/stp/

       It probably compiles on most Linux systems, and most modern UNIX
       without much problem.

    The statements

       stp can process any text file. It only processes lines that begin with
       '@' (at). Any others are just printed as-is.

       I think it should be straight forward to use, once you know what the
       'commands' are. Each are a single line, beginning on a on a new line.
       You can make them span across several lines, only for readability, by
       putting a '\' (back-slash) at the end of the line, like:
       @define moo \
       blah
       which will be asumed as @define moo blah. To actually use a newline
       character in a statement, use the %nl macro.

      Using variables/macros

       You know what they are. Here's how to use them...
       @define name value
       Variable/macro names are words that begin with a '%' (percent),
       looking like %name. You can also do something like
       blah%{somemacro}blah. Note that they are only expanded in lines that
       begin with an @. You can pass arguements to macros, like
       %macro(arg1,arg2), which are set as %1 and %2 within the macro. For
       example, to make a macro to produce an HTML link, using the first
       argument as the link destination, and the 2nd as the next, you'd do:
       @define link <a href="%1">%2</a>
       So %link(aaaa,moo) will produce <a href="aaaa">moo</a>.
       There are several pre-defined macros, which are described later

      Conditional execution

       @if, @ifnot, @elseif, @elseifnot, @else and @endif. It shouldn't be
       too hard to figure out what these do. Here's an example:
       @if (something)
       process this stuff if something is true
       @elseif (something-else)
       process this stuff if something is not true, but something-else is.
       @else (something-else)
       process this stuff if neither something or something-else is true.
       @endif
       Yes, you can nest @if[not]..@endif statments within each other, and
       the @else* statements are optional (but only allowed inside
       @if[not]..@endif pairs).
       If you want, you can just use a single-lined @if[not] statement, like:
       @if (something) do this
       In that case, a following @endif is not needed.

      Other stuff

       @:text evaluates the macros in text. @exec command executes command
       and includes the output. This is passed to the shell (using
       system(3)). No, stp doesn't process the output of command, just
       includes it as-is. You can, however, work around this with @exec echo
       `command` | stp.

       @include file includes file as though it is part of the current file.
       The contents of these files are parsed by stp. This allows you to have
       standard headers, and stuff. If you don't want stp to parse the
       contents of this file, just do @exec cat file.

       @eof treats this position in the file as the end, and everything else
       after is is ignored... as simple as that.

    Built-in macros

       %date([format]) expands to the current date, in the specified format,
       defaulting to what would produce "Mon Sep 25 19:02:27 2000". See the
       man pages strftime(3) or date(1) for more information on the format.

       %time([format]) is just the same as %date, but the default for format
       being "%H:%M:%S".

       %filename expands to the name of the file (as specified on the
       command-line, or @include) or nothing, if reading from standard input.

       %env(var) expands to the environment variable var.

       %nl puts in a newline character.

       %chr(num) does ascii character num.

       %asc(char) is the ascii number of char.

       %linenum is the current line-number of the current file.

       %rand([[min,]max]) produces a random number between min and max. min
       and max defaulting to 0 and 10,000 respectively.

       %pwd - print working directory; simple.

       %version - this version of stp.

       %stdin is 1 if reading from standard input, or 0 if reading from a
       file, either specified from the command line, or a @include line.

         _________________________________________________________________

       Copyright (c) 2000 Steve Grundell

       stp@grundell.u-net.com
       http://www.grundell.u-net.com/stp/