| blob | 8a72f42c2c67965b33c47ffdfdf9db0e5d001cf5 |
1 '\" t -- preprocess: tbl(1)
2 .ig
3 @ @L_P_GRN@.1
5 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
7 Copyright (C) 2000 - 2004, 2006
8 Free Software Foundation, Inc.
10 Permission is granted to make and distribute verbatim copies of
11 this manual provided the copyright notice and this permission notice
12 are preserved on all copies.
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
19 Permission is granted to copy and distribute translations of this
20 manual into another language, under the above conditions for modified
21 versions, except that this permission notice may be included in
22 translations approved by the Free Software Foundation instead of in
23 the original English.
24 ..
25 .
26 .do nr grn_C \n[.C]
27 .cp 0
28 .
29 .de TQ
30 . br
31 . ns
32 . TP \\$1
33 ..
34 .
35 .\" Like TP, but if specified indent is more than half
36 .\" the current line-length - indent, use the default indent.
37 .de Tp
38 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
39 . el .TP "\\$1"
40 ..
41 .
42 .
43 .TH @U_P_GRN@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
44 .SH NAME
45 @L_P_GRN@ \- preprocessor for gremlin files
46 .SH SYNOPSIS
47 .BR @L_P_GRN@
48 [
49 .B \-Cv
50 ]
51 [
52 .BI \-T dev
53 ]
54 [
55 .BI \-M dir
56 ]
57 [
58 .BI \-F dir
59 ]
60 [
61 .IR file\.\.\.\&
62 ]
63 .PP
64 It is possible to have whitespace between a command line option and its
65 parameter.
66 .SH DESCRIPTION
67 .I @L_P_GRN@
68 is a preprocessor for including
69 .I gremlin
70 pictures in
71 .I @L_ROFF@
72 input.
73 .I @L_P_GRN@
74 writes to standard output, processing only input lines between two that
75 start with
76 .B .GS
77 and
78 .BR .GE.
79 Those lines must contain
80 .I @L_P_GRN@
81 commands (see below).
82 These commands request a
83 .I gremlin
84 file, and the picture in that file is
85 converted and placed in the
86 .I @L_TROFF@
87 input stream.
88 The
89 .B .GS
90 request may be followed by a C, L, or R to center, left, or right
91 justify the whole
92 .I gremlin
93 picture (default justification is center).
94 If no
95 .I file
96 is mentioned, the standard input is read.
97 At the end of the picture, the position on the page is the bottom of the
98 .I gremlin
99 picture.
100 If the entry is ended with
101 .B .GF
102 instead of
103 .BR .GE ,
104 the position is left at the top of the picture.
105 .PP
106 Please note that currently only the \-me macro package has support for
107 .BR .GS ,
108 .BR .GE ,
109 and
110 .BR .GF .
111 .PP
112 The following command-line options are understood:
113 .TP
114 .BI \-T dev
115 Prepare output for printer
116 .IR dev .
117 The default device is
118 .BR @DEVICE@ .
119 See
120 .BR @L_ROFF@ (@MAN1EXT@)
121 for acceptable devices.
122 .TP
123 .BI \-M dir
124 Prepend
125 .I dir
126 to the default search path for
127 .I gremlin
128 files.
129 The default path is (in that order) the current directory, the home
130 directory,
131 .BR @SYSTEMMACRODIR@ ,
132 .BR @LOCALMACRODIR@ ,
133 and
134 .BR @MACRODIR@ .
135 .TP
136 .BI \-F dir
137 Search
138 .I dir
139 for subdirectories
140 .BI dev name
141 .RI ( name
142 is the name of the device) for the
143 .B DESC
144 file before the default font directories
145 .BR @LOCALFONTDIR@ ,
146 .BR @FONTDIR@ ,
147 and
148 .BR @LEGACYFONTDIR@ .
149 .TP
150 .B \-C
151 Recognize
152 .B .GS
153 and
154 .B .GE
155 (and
156 .BR .GF )
157 even when followed by a character other than space or newline.
158 .\".TP
159 .\".B \-s
160 .\"This switch causes the picture to be traversed twice:
161 .\"The first time, only the interiors of filled polygons (as borderless
162 .\"polygons) are printed.
163 .\"The second time, the outline is printed as a series of line segments.
164 .\"This way, postprocessors that overwrite rather than merge picture elements
165 .\"(such as Postscript) can still have text and graphics on a shaded
166 .\"background.
167 .TP
168 .B \-v
169 Print the version number.
170 .SH GRN COMMANDS
171 Each input line between
172 .B .GS
173 and
174 .B .GE
175 may have one
176 .I @L_P_GRN@
177 command.
178 Commands consist of one or two strings separated by white space, the first
179 string being the command and the second its operand.
180 Commands may be upper or lower case and abbreviated down to one character.
181 .PP
182 Commands that affect a picture's environment (those listed before
183 .BR default ,
184 see below) are only in effect for the current picture:
185 The environment is reinitialized to the defaults at the start of the next
186 picture.
187 The commands are as follows:
188 .TP
189 .BI 1\ N
190 .TQ
191 .BI 2\ N
192 .TQ
193 .BI 3\ N
194 .TQ
195 .BI 4\ N
196 Set
197 .IR gremlin 's
198 text size number 1 (2, 3, or 4) to
199 .I N
200 points.
201 The default is 12 (16, 24, and 36, respectively).
202 .TP
203 .BI roman\ f
204 .TQ
205 .BI italics\ f
206 .TQ
207 .BI bold\ f
208 .TQ
209 .BI special\ f
210 Set the roman (italics, bold, or special) font to
211 .IR @L_TROFF@ 's
212 font
213 .I f
214 (either a name or number).
215 The default is R (I, B, and S, respectively).
216 .TP
217 .BI l\ f
218 .TQ
219 .BI stipple\ f
220 Set the stipple font to
221 .IR @L_TROFF@ 's
222 stipple font
223 .I f
224 (name or number).
225 The command
226 .B stipple
227 may be abbreviated down as far as `st' (to avoid
228 confusion with
229 .BR special ).
230 There is
231 .I no
232 default for stipples (unless one is set by the default command), and it is
233 invalid to include a
234 .I gremlin
235 picture with polygons without specifying a
236 stipple font.
237 .TP
238 .BI x\ N
239 .TQ
240 .BI scale\ N
241 Magnify the picture (in addition to any default magnification) by
242 .IR N ,
243 a floating point number larger than zero.
244 The command
245 .B scale
246 may be abbreviated down to `sc'.
247 .TP
248 .BI narrow\ N
249 .TQ
250 .BI medium\ N
251 .TQ
252 .BI thick\ N
253 Set the thickness of
254 .IR gremlin 's
255 narrow (medium and thick, respectively) lines to
256 .I N
257 times 0.15pt (this value can be changed at compile time).
258 The default is 1.0 (3.0 and 5.0, respectively), which corresponds to 0.15pt
259 (0.45pt and 0.75pt, respectively).
260 A thickness value of zero selects the smallest available line thickness.
261 Negative values cause the line thickness to be proportional to the current
262 point size.
263 .TP
264 .BI pointscale\ <off/on>
265 Scale text to match the picture.
266 Gremlin text is usually printed in the point size specified with the
267 commands
268 .BR 1 ,
269 .BR 2 ,
270 .BR 3 ,
271 .RB or\~ 4 ,
272 regardless of any scaling factors in the picture.
273 Setting
274 .B pointscale
275 will cause the point sizes to scale with the picture (within
276 .IR @L_TROFF@ 's
277 limitations, of course).
278 An operand of anything but
279 .I off
280 will turn text scaling on.
281 .TP
282 .B default
283 Reset the picture environment defaults to the settings in the current
284 picture.
285 This is meant to be used as a global parameter setting mechanism at the
286 beginning of the
287 .I @L_TROFF@
288 input file, but can be used at any time to reset the
289 default settings.
290 .TP
291 .BI width\ N
292 Forces the picture to be
293 .I N
294 inches wide.
295 This overrides any scaling factors present in the same picture.
296 .RB ` width
297 .IR 0 '
298 is ignored.
299 .TP
300 .BI height\ N
301 Forces picture to be
302 .I N
303 inches high, overriding other scaling factors.
304 If both `width' and `height' are specified the tighter constraint will
305 determine the scale of the picture.
306 .B Height
307 and
308 .B width
309 commands are not saved with a
310 .B default
311 command.
312 They will, however, affect point size scaling if that option is set.
313 .TP
314 .BI file\ name
315 Get picture from
316 .I gremlin
317 file
318 .I name
319 located the current directory (or in the library directory; see the
320 .B \-M
321 option above).
322 If two
323 .B file
324 commands are given, the second one overrides the first.
325 If
326 .I name
327 doesn't exist, an error message is reported and processing continues from
328 the
329 .B .GE
330 line.
331 .SH NOTES ABOUT @U_ROFF@
332 Since
333 .I @L_P_GRN@
334 is a preprocessor, it doesn't know about current indents, point sizes,
335 margins, number registers, etc.
336 Consequently, no
337 .I @L_TROFF@
338 input can be placed between the
339 .B .GS
340 and
341 .B .GE
342 requests.
343 However,
344 .I gremlin
345 text is now processed by
346 .IR @L_TROFF@ ,
347 so anything valid in a single line of troff input is valid in a line of
348 .I gremlin
349 text (barring `.' directives at the beginning of a line).
350 Thus, it is possible to have equations within a
351 .I gremlin
352 figure by including in the
353 .I gremlin
354 file
355 .I eqn
356 expressions enclosed by previously defined delimiters (e.g.
357 .IR $$ ).
358 .PP
359 When using
360 .I @L_P_GRN@
361 along with other preprocessors, it is best to run
362 .I tbl
363 before
364 .IR @L_P_GRN@ ,
365 .IR pic ,
366 and/or
367 .I ideal
368 to avoid overworking
369 .IR tbl .
370 .I Eqn
371 should always be run last.
372 .PP
373 A picture is considered an entity, but that doesn't stop
374 .I @L_TROFF@
375 from trying to break it up if it falls off the end of a page.
376 Placing the picture between `keeps' in \-me macros will ensure proper
377 placement.
378 .PP
379 .I @L_P_GRN@
380 uses
381 .IR @L_TROFF@ 's
382 number registers
383 .B g1
384 through
385 .B g9
386 and sets registers
387 .B g1
388 and
389 .B g2
390 to the width and height of the
391 .I gremlin
392 figure (in device units) before entering the
393 .B .GS
394 request (this is for those who want to rewrite these macros).
395 .SH GREMLIN FILE FORMAT
396 There exist two distinct
397 .I gremlin
398 file formats, the original format from the
399 .I AED
400 graphic terminal version, and the
401 .I SUN
402 or
403 .I X11
404 version.
405 An extension to the
406 .IR SUN / X11
407 version allowing reference points with negative coordinates is
408 .B not
409 compatible with the
410 .I AED
411 version.
412 As long as a
413 .I gremlin
414 file does not contain negative coordinates, either format will be read
415 correctly by either version of
416 .I gremlin
417 or
418 .IR @L_P_GRN@ .
419 The other difference to the
420 .IR SUN / X11
421 format is the use of names for picture objects (e.g., POLYGON, CURVE)
422 instead of numbers.
423 Files representing the same picture are shown in Table 1 in each format.
424 .sp
425 .TS
426 center, tab(@);
427 l lw(0.1i) l.
428 sungremlinfile@@gremlinfile
429 0 240.00 128.00@@0 240.00 128.00
430 CENTCENT@@2
431 240.00 128.00@@240.00 128.00
432 185.00 120.00@@185.00 120.00
433 240.00 120.00@@240.00 120.00
434 296.00 120.00@@296.00 120.00
435 *@@-1.00 -1.00
436 2 3@@2 3
437 10 A Triangle@@10 A Triangle
438 POLYGON@@6
439 224.00 416.00@@224.00 416.00
440 96.00 160.00@@96.00 160.00
441 384.00 160.00@@384.00 160.00
442 *@@-1.00 -1.00
443 5 1@@5 1
444 0@@0
445 -1@@-1
446 .T&
447 css.
448 .sp
449 Table 1. File examples
450 .TE
451 .sp
452 .IP \(bu
453 The first line of each
454 .I gremlin
455 file contains either the string
456 .B gremlinfile
457 .RI ( AED
458 version) or
459 .B sungremlinfile
460 .RI ( SUN / X11 )
461 .IP \(bu
462 The second line of the file contains an orientation, and
463 .B x
464 and
465 .B y
466 values for a positioning point, separated by spaces.
467 The orientation, either
468 .B 0
469 or
470 .BR 1 ,
471 is ignored by the
472 .IR SUN / X11
473 version.
474 .B 0
475 means that
476 .I gremlin
477 will display things in horizontal format (drawing area wider than it is
478 tall, with menu across top).
479 .B 1
480 means that
481 .I gremlin
482 will display things in vertical format (drawing area taller than it is wide,
483 with menu on left side).
484 .B x
485 and
486 .B y
487 are floating point values giving a positioning point to be used when this
488 file is read into another file.
489 The stuff on this line really isn't all that important; a value of ``1 0.00
490 0.00'' is suggested.
491 .IP \(bu
492 The rest of the file consists of zero or more element specifications.
493 After the last element specification is a line containing the string ``-1''.
494 .IP \(bu
495 Lines longer than 127 characters are chopped to this limit.
496 .SH ELEMENT SPECIFICATIONS
497 .IP \(bu
498 The first line of each element contains a single decimal number giving the
499 type of the element
500 .RI ( AED
501 version) or its ASCII name
502 .RI ( SUN / X11
503 version).
504 See Table 2.
505 .sp
506 .TS
507 center, tab(@);
508 css
509 ccc
510 nll.
511 \fIgremlin\fP File Format \(mi Object Type Specification
512 .sp
513 \fIAED\fP Number@\fISUN\fP/\fIX11\fP Name@Description
514 0@BOTLEFT@bottom-left-justified text
515 1@BOTRIGHT@bottom-right-justified text
516 2@CENTCENT@center-justified text
517 3@VECTOR@vector
518 4@ARC@arc
519 5@CURVE@curve
520 6@POLYGON@polygon
521 7@BSPLINE@b-spline
522 8@BEZIER@B\['e]zier
523 10@TOPLEFT@top-left-justified text
524 11@TOPCENT@top-center-justified text
525 12@TOPRIGHT@top-right-justified text
526 13@CENTLEFT@left-center-justified text
527 14@CENTRIGHT@right-center-justified text
528 15@BOTCENT@bottom-center-justified text
529 .T&
530 css.
531 .sp
532 Table 2.
533 Type Specifications in \fIgremlin\fP Files
534 .TE
535 .sp
536 .IP \(bu
537 After the object type comes a variable number of lines, each specifying a
538 point used to display the element.
539 Each line contains an x-coordinate and a y-coordinate in floating point
540 format, separated by spaces.
541 The list of points is terminated by a line containing the string ``-1.0
542 -1.0''
543 .RI ( AED
544 version) or a single asterisk, ``*''
545 .RI ( SUN / X11
546 version).
547 .IP \(bu
548 After the points comes a line containing two decimal values, giving the
549 brush and size for the element.
550 The brush determines the style in which things are drawn.
551 For vectors, arcs, and curves there are six valid brush values:
552 .sp
553 .TS
554 center, tab(@);
555 ncw(0.1i)l.
556 1 \(mi@@thin dotted lines
557 2 \(mi@@thin dot-dashed lines
558 3 \(mi@@thick solid lines
559 4 \(mi@@thin dashed lines
560 5 \(mi@@thin solid lines
561 6 \(mi@@medium solid lines
562 .TE
563 .sp
564 For polygons, one more value, 0, is valid.
565 It specifies a polygon with an invisible border.
566 For text, the brush selects a font as follows:
567 .sp
568 .TS
569 center, tab(@);
570 ncw(0.1i)l.
571 1 \(mi@@roman (R font in @L_ROFF@)
572 2 \(mi@@italics (I font in @L_ROFF@)
573 3 \(mi@@bold (B font in @L_ROFF@)
574 4 \(mi@@special (S font in @L_ROFF@)
575 .TE
576 .sp
577 If you're using
578 .I @L_P_GRN@
579 to run your pictures through
580 .IR @L_ROFF@ ,
581 the font is really just a starting font:
582 The text string can contain formatting sequences like
583 ``\efI''
584 or
585 ``\ed''
586 which may change the font (as well as do many other things).
587 For text, the size field is a decimal value between 1 and 4.
588 It selects the size of the font in which the text will be drawn.
589 For polygons, this size field is interpreted as a stipple number to fill the
590 polygon with.
591 The number is used to index into a stipple font at print time.
592 .IP \(bu
593 The last line of each element contains a decimal number and a string of
594 characters, separated by a single space.
595 The number is a count of the number of characters in the string.
596 This information is only used for text elements, and contains the text
597 string.
598 There can be spaces inside the text.
599 For arcs, curves, and vectors, this line of the element contains the string
600 ``0''.
601 .SH NOTES ON COORDINATES
602 .I gremlin
603 was designed for
604 .IR AED s,
605 and its coordinates reflect the
606 .I AED
607 coordinate space.
608 For vertical pictures, x-values range 116 to 511, and y-values from 0 to
609 483.
610 For horizontal pictures, x-values range from 0 to 511 and y-values range
611 from 0 to 367.
612 Although you needn't absolutely stick to this range, you'll get best results
613 if you at least stay in this vicinity.
614 Also, point lists are terminated by a point of (-1, -1), so you shouldn't
615 ever use negative coordinates.
616 .I gremlin
617 writes out coordinates using format ``%f1.2''; it's probably a good idea to
618 use the same format if you want to modify the
619 .I @L_P_GRN@
620 code.
621 .SH NOTES ON SUN/X11 COORDINATES
622 There is no longer a restriction on the range of coordinates used to create
623 objects in the
624 .IR SUN / X11
625 version of
626 .IR gremlin .
627 However, files with negative coordinates
628 .B will
629 cause problems if displayed on the
630 .IR AED .
631 .SH FILES
632 .Tp \w'@FONTDIR@/devname/DESC'u+3n
633 .BI @FONTDIR@/dev name /DESC
634 Device description file for device
635 .IR name .
636 .SH SEE ALSO
637 .BR gremlin (1),
638 .BR @L_ROFF@ (@MAN1EXT@),
639 .BR @L_P_PIC@ (@MAN1EXT@),
640 .BR ideal (1)
641 .SH HISTORY
642 .PP
643 David Slattengren and Barry Roitblat wrote the original Berkeley
644 .IR @L_P_GRN@ .
645 .PP
646 Daniel Senderowicz and Werner Lemberg modified it for
647 .IR groff .
648 .
649 .cp \n[grn_C]
650 .
651 .\" s-ts-mode