1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
#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"]
@; ----------------------------------------
|
