Garbo/Garbo.cdr/pc/source/texpp.zoo/texpp.1/README

Text File | 1990-04-04 | 14KB | 330 lines

 ***************************************************************************
 *                                       *
 *           texpp TeX preprocessor, Version 1.2.               *
 *              Laci Csirmaz, DIMACS - Rutgers               *
 *                   Feb. 25, 1990                   *
 *                                       *
 ***************************************************************************
 *    You are granted to use, modify, copy, redistribute this program any  *
 * way you want. However no warranties are made for this program or the    *
 * accopanying documentation.                           *
 *                                       *
 *    Please send your comments, suggestions, etc. to:               *
 *        [e-mail]                       *
 *                                       *
 ***************************************************************************


                       Tex Preprocessor  M A N U A L

    0. Introduction

    TeX, undoubtedly a very LOGICAL language, does not follow closely enough
the illogical nature of human beings. Using backslashes everywhere to signify
a special treatment of a word is logical, but, of course, tedious and a bit
boring. Whenever the word "alpha" appears in a text, with higher probability
than 0.9999 the author wishes the corresponding greek letter to appear, and
not this word. In the latter unlikely case, s/he is more willing to do some
extra word to make the (now) exception the rule, and save a lot of work.
    Another drawback is the (also very logical, but unnatural) handling of
macros. If an operator is applied to a word (or a single letter), TeX
requires the operator to precede its argument. While in some cases this
is the natural approach, in some cases it is not. As in using a dot, tilde,
or hat on a letter, the natural form is "x tilde", and not what is the
obligatory form, "\tilde x".
    TeX forbids almost all key combinations to use as macro names, only
sequences of letters are allowed. Why cannot I write "|==" instead of
"\model", "/0" for "\empty", or, horribile dictu, "/\" instead of "\wedge"?
Formulas written in this way are more readable, and easier to type.
    Finally, while TeX (and LaTeX) allows to redefine its macros, the user
is usually not aware of its danger. Both plain TeX and LaTeX have a lot of
built-in macros which are absolutely necessary to run them. Redefining any
of them the program simply goes crazy. And, in most of the cases, the user
does not even know why the construct is wrong. What happens, for example,
if "\and" is redefined in LaTeX so that it would produce the sign /\ -- a
quite reasonable assumption. To avoid all the problems arising this way, TeX
should do these definitions locally, which it doesn't.

    All of the above problems lead to the development of the "texpp" TeX
preprocessor. Since TeX is quite ambivalent about handling the input layout
(often it says to be independent of whitespaces, but two consecutive newlines
signify a new paragraph, and comments are closed by newlines), I decided to
use layout a bit more significantly than TeX does. All macro definitions
should start at the first column. The preprocessor is not intended to be as
general as possible. It has a lot of wired in features (for example, the $
and $$ to start and end math mode), but the C code is available, and (at
least I hope) can be modified easily. Also, the preprocessor is absolutely
NOT for TeX wizards. It can be fooled quite easily e.g. by redefining the
escape character, but as far as it is used as a simple tool it works fine.


    1. Shipped files

    Besides the C source code of the program and this manual, you can find
a sample macro file which show some extra features of texpp. Also I wrote
a tex-mode.el (gnu)emacs template which embeds the 'texpp' preprocessor, and
a dvi viewer.
    The program was written for UNIX(TM) machines, but the code is highly
portable (at least I hope so). Therefore it should be easy yo transport to
other machines.


    2. Macro names

    Macro name can be any sequence of characters which does not contain
braces `{' and `}', dollar sign `$', percentage sign `%', and embedded
whitespaces. `Character' here means a character with ASCII code >=32 and
<= 126. Each line of the text is cut at braces and whitespaces, and what
is left is compared against the list of macro names. If there is a hit, then
the closing braces or white spaces are erased, and the macro text is replaced.

    3. Parameters

    A macro may have up to nine parameters, which can be either before or
after the macro name. Parameters are parsed starting from the macro name:
each parameter is either enclosed into braces, or contains no braces and is
enclosed by whitespaces. A parameter must have balanced braces, if any.
In braces, it may have embedded white spaces. Parameters may contain further
macro names, too, but parameter parsing is done BEFORE macro substitution.
Two macros cannot share parameters. A parameter is always stripped off its
enclosing characters, and then a macro substitution is executed on it. A
parameter can be a macro name with further parameters (see the examples).
If the macro name is enclosed into braces, all its parameters must also be
inside.


    4. Macro definition

    Macros can be defined anywhere. A definition always starts at the first
character of the line, and signified by the key words `%define' or `%mdefine'.
(Starting with percentage sign, but NO BACKSLASH is here). The form of a
definition is the following:

    %define <preceeding pars> name <follow up pars>  %text% <any comment>

Local parameters are of the form #1, #2, ..., #9. No parameters are required,
they can appear in any order and in any place. The REPLACEMENT text is enclosed
by `%' characters (thus it cannot contain `%', but of course it may contain
the `\%' pair!), and is used as it is, with the following exeptions:

    a) local parameters #1, ... #9 are replaced by the stripped and
       expanded parameters of the invocation;
    b) the pair ## is replaced by a single # mark.
    c) macro calls are expanded.

Rule b) also applies to the macro name. Thus `#' can also appear in a macro
name, but should be written as `##'. (Of course, when looking for a macro name
in the text, this corresponds to the single character!)
    Macro definitions starting by `%mdefine' are applied only when in math
or displayed math mode; other definitions are always applicable. The program
assumes that the macro body does not switch these modes.
    Besides defining macros, you can "undefine" them, too. This comes handy
when a macro is used only as an auxiliary in a more complicated definition,
but not needed later. A new definition "hides" the old one, undefining
restores the old meaning. This can be done by

    %undefine name
or
    %undefine name % <your comment here>

It is an error to undefine a macro which was not defined (or mdefined)
before.

    5. Auxiliary tools

    In certain cases it is essential to suppress macro substitution. This
can be done by applying the `\preserve' keyword to its single parameter:

    \preserve <anything_which_does_not_contain_whitespace_or_brace>
or
    \preserve {<any text with balanced braces>}

In the parameter to `\preserve' no macro substitution is made. However,
`\preserve' cannot be applied to macro parameters in macro definitions,
since parameter expansion is done BEFORE substitution.

    Different extensions of TeX use different macros to switch to and from
math mode. To comply with them, the following definitions are recognized:

    %mathmode <string_to_enter_math_mode>  <string_leave_math_mode>
and
    %dispmode <string_to_enter_displayed_math>  <string_leaving>

The strings cannot contain white spaces, and if only one string is given in
a definition, then that is used for both entering and leaving math mode.
In LaTeX the following definitions may come handy:

    %mathmode \( \)            %simple math mode
    %mathmode \math \endmath
    %dispmode \[ \]            %displayed formulas
    %dispmode \equation \endequation    %for numbered formulas


    6. Examples

o 6.1. The first example defines the `*16' macro, which repeats its argument
 sixteen times:

 %define #1 *2 %#1#1%        %define `*2' as an auxiliary macro
 %define #1 *16 %#1 *2 *2 *2 *2%
 %undefine *2            %undefine `*2', no more needed

 Texts `x 1 *16 y' and `x{1}*16 y' expand to `x1111111111111111y'. (Observe
 that the trailing space after `*16' vanished). At the same time `x 1*16 y'
 and `x 1 *16y' remain unchanged since the macro name `*16' cannot be
 extracted.  As another example, `x {a b} *16 y' saves the space between `a'
 and `b', and before the open brace but not after the macro name. So the
 result is

    `x a ba ba ba ba ba ba ba ba ba ba ba ba ba ba ba by'


o 6.2. The next example also shows that macro definitions are expanded when
 defined, and not when invoked. This means, for example, that subsequent
 macro definitions have no influence on an existing macro definition. This
 fact is used here:

 %define [[  %[%    define [[ as a macro to be substituted by [
 %define ]]  %]%    define ]] as a macro to be substituted by ]
 %define [   %\{%    now define [ to mean \{
 %define ]   %\}%    and define ] to mean \}

 The last two definitions make a text like

    a = [ 0, 1, 2, ..., n ] + [ 2n, ..., 4n ]

 to transform to

    a =\{0, 1, 2, ..., n\}+\{2n, ..., 4n\}

 while, e.g. a reference can be put into square brackets by using double
 brackets: ` [[ 1 ]] ' which becomes `[1]'. Changing the last two and first
 two definitions here, the definition of `[[' becomes identical to that of
 `[', i.e. with `\{'.


o 6.3. Our third example defines some model-theoretical stuff:

 %mdefine /\   % \wedge %           and sign
 %mdefine \/   % \vee %             or sign
 %mdefine |--  % \vdash %           syntactically follows
 %mdefine |==  % \models %          semantically follows
 %mdefine -->  % \rightarrow %       implies
 %mdefine phi  % \varphi %
 %mdefine ALL  % \forall %
 %mdefine not  % \neg %
 %mdefine ...  % \ldots %           ellipsis notation

 Since the preprocessor does not treat the backslash as a special symbol,
 `/\' and `\/' will be recognized without any trouble. The spaces at the
 end of each definition are necessary because before replacing the macro
 name, its surrounding white spaces (or braces) are deleted. So displayed
 formulas can be written as, e.g.

    $$ |== ALL x ( phi (x) \/ not phi (x) ) $$
    $$ |-- phi --> ( not phi --> phi ) $$


o 6.4. Sometimes it is convenient to use `**' to denote exponentiation:

 %mdefine #1 ** #2 %#1^{#2}%

 Here ` e ** { x ** 2 / 2 } ' or ` e **{x ** 2 /2}' becomes `e^{x^{2}/ 2 } '
 (look out for the spaces!). The braces around #2 in the definition are
 necessary to ensure that all the second parameter shows up in the exponent.
 Without those braces the expanded form of the first form would be
 `e^x^2/ 2 ', evidently not what was intended.


o 6.5. The next example shows how to use "before" parameters when they are
 handy:

 %mdefine #1 tilde %\wildetilde{#1}%
 %mdefine #1 hat %\wildehat{#1}%

 After these definition the following text
    ...
    a+b tilde = a tilde + b tilde
    ...
 expands to
    ...
    \wildetilde{a+b}=\wildetilde{a}+\wildetilde{b}
    ...
 Which one is easier to read?


o 6.6. To overcome the problem corresponding to greek letters, one can define

 %define alpha %$\alpha$%

 (since greek letters are allowed in math mode only.) With this definition,
 however, there are certain problems. Using this macro in the text `Let alpha
 be the ...', the substitution mechanism erases ALL the spaces around the word
 `alpha', and the result is `Let$\alpha$be the ...'. Evidently no what was
 wanted. Changing the definition to

 %define alpha % $\alpha$ % now with spaces

 will put back the spaces both BEFORE and AFTER the word, thus giving
    Let $\alpha$ be the ...
       ^^^^^^^^^^-- substituted text
 Having this latter definition, however, you cannot write alpha's without
 intervening spaces. Another problem is that this definition cannot be used in
 math mode! A possible solution is that the macro `alpha' will be used in math
 mode only, now with the definition

 %mdefine alpha %\alpha %

 The above sentence can be written as `Let $alpha$ be the ...'. Also, two
 consecutive alpha's can be produced as

    `here are two $alpha$'s: $alpha alpha$'.

 The word alpha, if found not in math mode, won't change. And, if you want
 to use the word alpha in math (or displayed) mode, you can use the \preserve
 keyword:
    I can write $\preserve alpha$ in math mode.


o 6.7. Strings used to switch to and from math mode are also subject to macro
 replacement. Thus using the definitions

 \def\mydisplayformula#1#2{ $$ #2 \leqno #1 $$}
 %dispmode .EQ .EN
 %define .EQ #1 % \mydisplayformula{#1}{ %
 %define .EN % } %

 an eqn-like construct for display formulas can be used so that the formula
 number (written after .EQ) appears on the left of the displayed formula.
 However, if you don't want this number to appear, you still have to submit
 a parameter, which can be the empty string, i.e. `{}'


   7. How to use the preprocessor?

To compile the program on a UNIX machine, simply invoke cc by typing

        cc texpp.c -o texpp

On certain systems the 'strdup()' function is missing from the standard C
library. In this case, recompile the program by

        cc -DSTRDUP texpp.c -o texpp

The preprocessor works as a filter. It reads one ore more input files,
processes them, and then produces a single output which can be the input
for TeX. The program can be invoked by typing

    texpp file1 file2 ... filen -[wa] output_file

`file1', ..., `filen' are processed in their given order; a file definition
consisting of a single `-' sign means read from stdin. The output goes to
`output_file', the file is overwritten if the name is preceded by `-w', and
is appended if `-a' is present. Error messages are inserted into the output
and are duplicated at stderr. If no input file is given, the program reads
from stdin; if no output file is given, then the output goes to stdout. When
the program halts, the exit value is 0 if `texpp' run successfully, if any
error occurred (cannot open a file or processing error) then the exit value
is 1.