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