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.