summaryrefslogtreecommitdiff
path: root/systems/doc/metapost/source-manual/grdemo-doc.ms
blob: 19c0ed030d7478ace6fdbd3f8dabb87bc973cad7 (plain)
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
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
.\" grdemo-doc.ms
.\"
.
.nr PS 11
.nr VS 13
.
.TL
MetaPost with groff
.
.LP
John Hobby's MetaPost program had an \f[I]AT&T troff\/\f[P]interface which
have been changed to use \f[I]GNU troff\/\f[P] instead.
.
.
.SH
Usage
.
.LP
Since MetaPost is a picture-drawing language that outputs PostScript, it is
necessary to use the \f[CW]\%-mpspic\f[P] macro package, which is
automatically included when \f[I]groff\/\f[P](1) is invoked with the
\f[CW]\%-Tps\f[P] option to prepare output for PostScript printers or
previewers.
.
.PP
Suppose you have written some figures in MetaPost and placed the input in a
file \f[CW]\%figures.mp\f[P].
Running
.
.DS I
.ft CW
mp -T figures
.ft
.DE
.
to invoke the MetaPost interpreter produces output files
\f[CW]\%figures.1\f[P], \f[CW]\%figures.2\f[P], \&.\|.\|.
.
.PP
Standalone EPS pictures can be produced from such files by
\f[CW]\%fixgrofffonts\f[P], that fixes comments according to
Adobe Document Structuring Conventions (DSC), embeds
font reencoding commands and non-standard fonts.
.
.DS I
.nf
.ft CW
fixgrofffonts < figures.1 > figures1.eps 
fixgrofffonts < figures.2 > figures2.eps 
\&...
.ft
.fi
.DE
.
.PP
Before these figures can be included into \f[I]groff\/\f[P], they have to
be processed with the \f[CW]\%fixmp\f[P] script:
It adds an encoding vector for all text fonts back to the file (which
MetaPost can't add itself) and changes the Adobe Document Structuring
Conventions (DSC) comments to something \f[I]groff\/\f[P] can handle.
.
.DS I
.nf
.ft CW
fixmp < figures.1 > figures.1ps
fixmp < figures.2 > figures.2ps
\&...
.ft
.fi
.DE
.
Now the converted files can be included in a \f[I]groff\/\f[P] document via
macro calls such as
.
.DS I
.ft CW
\&.PSPIC figures.1ps [width [height]]
.ft
.DE
.
as explained in the \f[I]grops\/\f[P](1) documentation.
Note that the picture gets rescaled if the height and width in the
\f[CW]\%.PSPIC\f[P] command don't match \f[I]mp\/\f[P]'s idea of the
picture dimensions.
.
.
.SH
An example
.
.PSPIC grdemo.1ps
.
.LP
This figure was derived from a file \f[CW]\%grdemo.mp\f[P] and included at
this point by invoking the \f[CW]\%.PSPIC\f[P] macro (omitting the height
and width parameters to avoid rescaling).
.
.PP
The file \f[CW]\%grdemo.mp\f[P] looks like this:
.
.DS I
.nf
.ft CW
.ps 9
.vs 11
verbatimtex
\&.EQ
delim $$
\&.EN
\e# etex

input boxes

beginfig(1);
  pair shadowshift;
  shadowshift = (1, -1) * bp;

  def drawshadowed(text t) =
    forsuffixes $=t:
      fill bpath$ shifted shadowshift;
      unfill bpath$;
      drawboxed($);
    endfor
  enddef;

  boxit.a(btex \e[12] \es8A\es+2 \e[lh] a etex);
  circleit.b(btex $e sup {i omega t}$ etex rotated 20);

  b.w - a.e = (10bp, 0);

  drawshadowed(a, b);
  draw a.e .. b.w;

  label.top(btex \e[Cs] \e[Po] \e[Eu] etex, a.n);
  label.llft(btex \e[Fn] etex, a.s);

  draw bbox currentpicture dashed evenly;
endfig;

end
.ps 11
.vs 13
.ft
.fi
.DE
.
.
.SH
Changing GNU troff pipeline
.PP
Note that, by default, the typesetting commands in the \f[CW]\%btex\f[P]
\&.\|.\|.\& \f[CW]\%etex\f[P] blocks in the above example
are processed by
.
.DS I
.ft CW
eqn -Tps -d\e$\e$ | troff -Tps
.ft
.DE
.
If a different \f[I]troff\/\f[P] pipeline must be used it can be
specified via the \f[CW]\%TROFF\f[P] environment variable.
For \f[I]groff\f[P], the following is recommended:
.
.DS I
.ft CW
TROFF='groff -teZ'
.ft
.DE
.
It adds \f[I]tbl\/\f[P] to the pipeline in addition to \f[I]eqn\f[P],
producing output for \f[I]groff\/\f[P]'s default `ps' device.  Note that
you then have to specify the left and right delimiters of \f[I]eqn\/\f[P]'s
in-line equations within the document (which is good practice anyway).
.
.PP
Macro definitions and such can be added via the standard
\f[CW]\%verbatimtex\f[P] \&.\|.\|.\& \f[CW]\%etex\f[P] mechanism that adds
the given material to the \f[I]troff\/\f[P] input.
Such material should not generate any output since this would get mixed up
with the next \f[CW]\%btex\f[P] .\|.\|.\& \f[CW]\%etex\f[P] block.
Note the comment escape right before the first \f[CW]\%etex\f[P] command in
the above example to avoid an empty line.
.
.\" eof