1 Overview

The preprocessors can be invoked from Racket programs, but the main usage should be through the launchers. Both launchers use code from preprocessor/pp-run that allows a special invocation mode through the --run flag.

The --run is a convenient way of making the preprocessors cooperate with some other command, making it possible to use preprocessed text without an additional glue script or a makefile. The following examples use mzpp, but they work with mztext too. --run uses a single argument which is a string specifying a command to run:

• 1. In its simplest form, the command string specifies some shell command which will be executed with its standard input piped in from the preprocessor’s output. For example, mzpp --run pr foo is the same as mzpp foo | pr. An error is raised if an output file is specified with such an argument.

• 2. If the command string contains a * and an output file is specified, then the command will be executed on this output file after it is generated. For example, mzpp --run 'pr *' -o foo x y z is the same as mzpp -o foo x y z; pr foo.

• 3. If the command string contains a *, and no output file is specified, and there is exactly one input file, then a temporary file will be used to save the original while the command is running. For example, mzpp --run 'pr *' foo is the same as mv foo foo-mzpp-temporary; mzpp -o foo foo-mzpp-temporary; pr foo; rm foo; mv foo-mzpp-temporary foo. If there is an error while mzpp is running, the working file will be erased and the original will be renamed back.

• 4. Any other cases where the command string contains a * are invalid.

If an executed command fails with a return status different than 0, the preprocessor execution will signal a failure by returning 1.