3 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2009
4 Free Software Foundation, Inc.
6 Permission is granted to make and distribute verbatim copies of
7 this manual provided the copyright notice and this permission notice
8 are preserved on all copies.
10 Permission is granted to copy and distribute modified versions of this
11 manual under the conditions for verbatim copying, provided that the
12 entire resulting derived work is distributed under the terms of a
13 permission notice identical to this one.
15 Permission is granted to copy and distribute translations of this
16 manual into another language, under the above conditions for modified
17 versions, except that this permission notice may be included in
18 translations approved by the Free Software Foundation instead of in
31 .\" Like TP, but if specified indent is more than half
32 .\" the current line-length - indent, use the default indent.
34 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
39 .TH @G@GRN @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
41 @g@grn \- groff preprocessor for gremlin files
60 It is possible to have whitespace between a command line option and its
64 is a preprocessor for including
70 writes to standard output, processing only input lines between two that
75 Those lines must contain
78 These commands request a
80 file, and the picture in that file is
81 converted and placed in the
86 request may be followed by a C, L, or R to center, left, or right
89 picture (default justification is center).
92 is mentioned, the standard input is read.
93 At the end of the picture, the position on the page is the bottom of the
102 the position is left at the top of the picture.
104 Please note that currently only the \-me macro package has support for
110 The following command-line options are understood:
113 Prepare output for printer
115 The default device is
118 .BR groff (@MAN1EXT@)
119 for acceptable devices.
124 to the default search path for
127 The default path is (in that order) the current directory, the home
129 .BR @SYSTEMMACRODIR@ ,
130 .BR @LOCALMACRODIR@ ,
140 is the name of the device) for the
142 file before the default font directories
146 .BR @LEGACYFONTDIR@ .
155 even when followed by a character other than space or newline.
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
167 Print the version number.
169 Each input line between
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.
180 Commands that affect a picture's environment (those listed before
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
185 The commands are as follows:
196 text size number 1 (2, 3, or 4) to
199 The default is 12 (16, 24, and 36, respectively).
208 Set the roman (italics, bold, or special) font to
212 (either a name or number).
213 The default is R (I, B, and S, respectively).
218 Set the stipple font to
225 may be abbreviated down as far as `st' (to avoid
230 default for stipples (unless one is set by the default command), and it is
233 picture with polygons without specifying a
239 Magnify the picture (in addition to any default magnification) by
241 a floating point number larger than zero.
244 may be abbreviated down to `sc'.
253 narrow (medium and thick, respectively) lines to
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
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
270 regardless of any scaling factors in the picture.
273 will cause the point sizes to scale with the picture (within
275 limitations, of course).
276 An operand of anything but
278 will turn text scaling on.
281 Reset the picture environment defaults to the settings in the current
283 This is meant to be used as a global parameter setting mechanism at the
286 input file, but can be used at any time to reset the
290 Forces the picture to be
293 This overrides any scaling factors present in the same picture.
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.
307 commands are not saved with a
310 They will, however, affect point size scaling if that option is set.
317 located the current directory (or in the library directory; see the
322 commands are given, the second one overrides the first.
325 doesn't exist, an error message is reported and processing continues from
329 .SH NOTES ABOUT GROFF
332 is a preprocessor, it doesn't know about current indents, point sizes,
333 margins, number registers, etc.
336 input can be placed between the
343 text is now processed by
345 so anything valid in a single line of
347 input is valid in a line of
349 text (barring `.' directives at the beginning of a line).
350 Thus, it is possible to have equations within a
352 figure by including in the
356 expressions enclosed by previously defined delimiters (e.g.
361 along with other preprocessors, it is best to run
371 should always be run last.
373 A picture is considered an entity, but that doesn't stop
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
390 to the width and height of the
392 figure (in device units) before entering the
394 request (this is for those who want to rewrite these macros).
395 .SH GREMLIN FILE FORMAT
396 There exist two distinct
398 file formats, the original format from the
400 graphic terminal version, and the
407 version allowing reference points with negative coordinates is
414 file does not contain negative coordinates, either format will be read
415 correctly by either version of
419 The other difference to the
421 format is the use of names for picture objects (e.g., POLYGON, CURVE)
423 Files representing the same picture are shown in Table 1 in each format.
428 sungremlinfile@@gremlinfile
429 0 240.00 128.00@@0 240.00 128.00
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
437 10 A Triangle@@10 A Triangle
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
449 Table 1. File examples
453 The first line of each
455 file contains either the string
462 The second line of the file contains an orientation, and
466 values for a positioning point, separated by spaces.
467 The orientation, either
477 will display things in horizontal format (drawing area wider than it is
478 tall, with menu across top).
482 will display things in vertical format (drawing area taller than it is wide,
483 with menu on left side).
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
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''.
495 Lines longer than 127 characters are chopped to this limit.
496 .SH ELEMENT SPECIFICATIONS
498 The first line of each element contains a single decimal number giving the
501 version) or its ASCII name
511 \fIgremlin\fP File Format \(mi Object Type Specification
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
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
533 Type Specifications in \fIgremlin\fP Files
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
544 version) or a single asterisk, ``*''
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:
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
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:
571 1 \(mi@@roman (R font in groff)
572 2 \(mi@@italics (I font in groff)
573 3 \(mi@@bold (B font in groff)
574 4 \(mi@@special (S font in groff)
579 to run your pictures through
581 the font is really just a starting font:
582 The text string can contain formatting sequences like
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
591 The number is used to index into a stipple font at print time.
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
598 There can be spaces inside the text.
599 For arcs, curves, and vectors, this line of the element contains the string
601 .SH NOTES ON COORDINATES
605 and its coordinates reflect the
608 For vertical pictures, x-values range 116 to 511, and y-values from 0 to
610 For horizontal pictures, x-values range from 0 to 511 and y-values range
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.
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
621 .SH NOTES ON SUN/X11 COORDINATES
622 There is no longer a restriction on the range of coordinates used to create
627 However, files with negative coordinates
629 cause problems if displayed on the
632 .Tp \w'@FONTDIR@/devname/DESC'u+3n
633 .BI @FONTDIR@/dev name /DESC
634 Device description file for device
638 .BR groff (@MAN1EXT@),
639 .BR @g@pic (@MAN1EXT@),
643 David Slattengren and Barry Roitblat wrote the original Berkeley
646 Daniel Senderowicz and Werner Lemberg modified it for