* src/preproc/grn/main.cc: Introduce BASE_THICKNESS, defining
[s-roff.git] / src / preproc / grn / grn.man
blob7197f1d4969f7b2820d7b8e549b84b187c60eab3
1 .de TQ
2 .br
3 .ns
4 .TP \\$1
5 ..
6 .\" Like TP, but if specified indent is more than half
7 .\" the current line-length - indent, use the default indent.
8 .de Tp
9 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
10 .el .TP "\\$1"
12 .TH @G@GRN @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
13 .SH NAME
14 @g@grn \- groff preprocessor for gremlin files
15 .SH SYNOPSIS
16 .BR @g@grn
17 [ options ] ... [
18 .I file
19 ] ...
20 .SH DESCRIPTION
21 .I @g@grn
22 is a preprocessor for including
23 .I gremlin
24 pictures in
25 .I groff
26 input.
27 .I @g@grn
28 writes to standard output, processing only input lines between two that
29 start with
30 .B .GS
31 and
32 .BR .GE.
33 Those lines must contain
34 .I @g@grn
35 commands (see below).
36 These commands request a
37 .I gremlin
38 file, and the picture in that file is
39 converted and placed in the
40 .I troff
41 input stream.
42 The
43 .B .GS
44 request may be followed by a C, L, or R to center, left, or right
45 justify the whole
46 .I gremlin
47 picture (default justification is center).
48 If no
49 .I file
50 is mentioned, the standard input is read.
51 At the end of the picture, the position on the page is the bottom of the
52 .I gremlin
53 picture.
54 If the
55 .I @g@grn
56 entry is ended with
57 .B .GF
58 instead of
59 .BR .GE ,
60 the position is left at the top of the picture.
61 .PP
62 Please note that currently only the \-me macro package has support for
63 .BR .GS ,
64 .BR .GE ,
65 and
66 .BR .GF .
67 .PP
68 The following command-line options are understood:
69 .TP
70 .BI \-T dev
71 Prepare output for printer
72 .IR dev .
73 The default device is
74 .BR @DEVICE@ .
75 See
76 .BR groff (@MAN1EXT@)
77 for acceptable devices.
78 .TP
79 .BI \-M dir
80 Set the library to directory
81 .IR dir .
82 If a
83 .I gremlin
84 file cannot be found in the current directory,
85 .I dir
86 is prepended to the filename for a second try.
87 The default library directory is
88 .BR @MACRODIR@ .
89 .TP
90 .BI \-F dir
91 Search
92 .I dir
93 for subdirectories
94 .BI dev name
95 .RI ( name
96 is the name of the device) for the
97 .B DESC
98 file before the normal
99 .BR @FONTDIR@ .
101 .B \-C
102 Recognize
103 .B .GS
105 .B .GE
106 (resp.
107 .BR .GF )
108 even when followed by a character other than space or newline.
110 .B \-s
111 This switch causes the picture to be traversed twice:
112 The first time, only the interiors of filled polygons (as borderless
113 polygons) are printed.
114 The second time, the outline is printed as a series of line segments.
115 This way, postprocessors that overwrite rather than merge picture elements
116 (such as Postscript) can still have text and graphics on a shaded
117 background.
119 .B \-v
120 Print the version number.
121 .SH GRN COMMANDS
122 Each input line between
123 .B .GS
125 .B .GE
126 may have one
127 .I @g@grn
128 command.
129 Commands consist of one or two strings separated by white space, the first
130 string being the command and the second its operand.
131 Commands may be upper or lower case and abbreviated down to one character.
133 Commands that affect a picture's environment (those listed before
134 .BR default ,
135 see below) are only in effect for the current picture:
136 The environment is reinitialized to the defaults at the start of the next
137 picture.
138 The commands are as follows:
140 .BI 1\  N
142 .BI 2\  N
144 .BI 3\  N
146 .BI 4\  N
148 .IR gremlin 's
149 text size number 1 (2, 3, or 4) to
150 .I N
151 points.
152 The default is 12 (resp. 16, 24, and 36).
154 .BI roman\  f
156 .BI italics\  f
158 .BI bold\  f
160 .BI special\  f
161 Set the roman (italics, bold, or special) font to
162 .IR troff 's
163 font
164 .I f
165 (either a name or number).
166 The default is R (resp. I, B, and S).
168 .BI l\  f
170 .BI stipple\  f
171 Set the stipple font to
172 .IR troff 's
173 stipple font
174 .I f
175 (name or number).
176 The command
177 .B stipple
178 may be abbreviated down as far as `st' (to avoid
179 confusion with
180 .BR special ).
181 There is
182 .I no
183 default for stipples (unless one is set by the default command), and it is
184 illegal to include a
185 .I gremlin
186 picture with polygons without specifying a
187 stipple font.
189 .BI x\  N
191 .BI scale\  N
192 Magnify the picture (in addition to any default magnification) by
193 .IR N ,
194 a floating point number larger than zero.
195 The command
196 .B scale
197 may be abbreviated down to `sc'.
199 .BI narrow\  N
201 .BI medium\  N
203 .BI thick\  N
204 Set the thickness of
205 .IR gremlin 's
206 narrow (resp. medium and thick) lines to
207 .I N
208 times 0.15pt
209 .RI ( N
210 must be an integer).
211 The default is 1 (resp. 3 and 5), which corresponds to 0.15pt
212 (resp. 0.45pt and 0.75pt).
214 .BI pointscale\  <off/on>
215 Scale text to match the picture.
216 Gremlin text is usually printed in the point size specified with the
217 commands
218 .BR 1 ,\  2 ,\  3 ,\ or\  4
219 regardless of any scaling factors in the picture.
220 Setting
221 .B pointscale
222 will cause the point sizes to scale with the picture (within
223 .IR troff 's
224 limitations, of course).
225 An operand of anything but
226 .I off
227 will turn text scaling on.
229 .B default
230 Reset the picture environment defaults to the settings in the current
231 picture.
232 This is meant to be used as a global parameter setting mechanism at the
233 beginning of the
234 .I troff
235 input file, but can be used at any time to reset the
236 default settings.
238 .BI width\  N
239 Forces the picture to be
240 .I N
241 inches wide.
242 This overrides any scaling factors present in the same picture.
243 .RB ` width
244 .IR 0 '
245 is ignored.
247 .BI height\  N
248 Forces picture to be
249 .I N
250 inches high, overriding other scaling factors.
251 If both `width' and `height' are specified the tighter constraint will
252 determine the scale of the picture.
253 .B Height
255 .B width
256 commands are not saved with a
257 .B default
258 command.
259 They will, however, affect point size scaling if that option is set.
261 .BI file\  name
262 Get picture from
263 .I gremlin
264 file
265 .I name
266 located the current directory (or in the library directory; see the
267 .B \-M
268 option above).
269 If two
270 .B file
271 commands are given, the second one overrides the first.
273 .I name
274 doesn't exist, an error message is reported and processing continues from
276 .B .GE
277 line.
278 .SH NOTES ABOUT GROFF
279 Since
280 .I @g@grn
281 is a preprocessor, it doesn't know about current indents, point sizes,
282 margins, number registers, etc.
283 Consequently, no
284 .I troff
285 input can be placed between the
286 .B .GS
288 .B .GE
289 requests.
290 However,
291 .I gremlin
292 text is now processed by
293 .IR troff ,
294 so anything legal in a single line of
295 .I troff
296 input is legal in a line of
297 .I gremlin
298 text (barring `.' directives at the beginning of a line).
299 Thus, it is possible to have equations within a
300 .I gremlin
301 figure by including in the
302 .I gremlin
303 file
304 .I eqn
305 expressions enclosed by previously defined delimiters (e.g.
306 .IR $$ ).
308 When using
309 .I @g@grn
310 along with other preprocessors, it is best to run
311 .I tbl
312 before
313 .IR @g@grn ,
314 .IR pic ,
315 and/or
316 .I ideal
317 to avoid overworking
318 .IR tbl .
319 .I Eqn
320 should always be run last.
322 A picture is considered an entity, but that doesn't stop
323 .I troff
324 from trying to break it up if it falls off the end of a page.
325 Placing the picture between `keeps' in \-me macros will ensure proper
326 placement.
328 .I @g@grn
329 uses
330 .IR troff 's 
331 number registers
332 .B g1
333 through
334 .B g9
335 and sets registers
336 .B g1
338 .B g2
339 to the width and height of the
340 .I gremlin
341 figure (in device units) before entering the
342 .B .GS
343 request (this is for those who want to rewrite these macros).
344 .SH FILES
345 .Tp \w'@FONTDIR@/devname/DESC'u+3n
346 .BI @FONTDIR@/dev name /DESC
347 Device description file for device
348 .IR name .
349 .SH SEE ALSO
350 .BR gremlin (1),
351 .BR groff (@MAN1EXT@),
352 .BR pic (@MAN1EXT@),
353 .BR ideal (1)
354 .SH HISTORY
356 David Slattengren and Barry Roitblat wrote the original Berkeley
357 .IR grn .
359 Daniel Senderowicz and Werner Lemberg modified it for
360 .IR groff .