ac26fe7554
Also, updates some of the mzlib files to point at `racket/*' libraries rather than to `scheme/*' ones.
75 lines
2.8 KiB
Racket
75 lines
2.8 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual
|
|
(for-label scheme/base
|
|
scheme/contract
|
|
scheme/port))
|
|
|
|
@title{@exec{mzpp} and @exec{mztext}: Preprocessors}
|
|
|
|
@author["Eli Barzilay"]
|
|
|
|
The @filepath{preprocessor} collection defines two Racket-based
|
|
preprocessors for texts that can have embedded Racket code. The two
|
|
processors share a few features, like several command-line flags and
|
|
the fact that embedded Racket code is case-sensitive by default.
|
|
|
|
Note that these processors are @bold{not} intended as preprocessors for
|
|
Racket code, since you have macros to do that.
|
|
|
|
@table-of-contents[]
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section[#:tag "overview"]{Overview}
|
|
|
|
@defmodule[preprocessor/pp-run]
|
|
|
|
The preprocessors can be invoked from Racket programs, but the main
|
|
usage should be through the launchers. Both launchers use code from
|
|
@racketmodname[preprocessor/pp-run] that allows a special invocation
|
|
mode through the @DFlag{run} flag.
|
|
|
|
The @DFlag{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 @exec{mzpp}, but they work with @exec{mztext} too. @DFlag{run} uses a single
|
|
argument which is a string specifying a command to run:
|
|
|
|
@itemize[
|
|
|
|
@item{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, @exec{mzpp --run pr foo} is the same
|
|
as @exec{mzpp foo | pr}. An error is raised if an output file is
|
|
specified with such an argument.}
|
|
|
|
@item{2. If the command string contains a @racket[*] and an output file is
|
|
specified, then the command will be executed on this output file after it is
|
|
generated. For example, @exec{mzpp --run 'pr *' -o foo x y z} is the same
|
|
as @exec{mzpp -o foo x y z; pr foo}.}
|
|
|
|
@item{3. If the command string contains a @racket[*], 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, @exec{mzpp --run 'pr *' foo} is the same as @exec{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 @exec{mzpp} is
|
|
running, the working file will be erased and the original will be
|
|
renamed back.}
|
|
|
|
@item{4. Any other cases where the command string contains a @litchar{*} are invalid.}
|
|
|
|
]
|
|
|
|
If an executed command fails with a return status different than 0, the
|
|
preprocessor execution will signal a failure by returning 1.
|
|
|
|
|
|
@; ----------------------------------------
|
|
@include-section["mzpp.scrbl"]
|
|
|
|
@; ----------------------------------------
|
|
@include-section["mztext.scrbl"]
|
|
|
|
@; ----------------------------------------
|