Debian Codegraph @

upstream/debian-unstable/man1/grn.1

raw
1 '\" t
2 .TH \%grn 1 "2026-04-22" "groff 1.24.1"
3 .SH Name
4 \%grn \- embed Gremlin images in
5 .I groff
6 documents
7 .
8 .
9 .\" ====================================================================
10 .\" Legal Terms
11 .\" ====================================================================
12 .\"
13 .\" Copyright (C) 2000-2024 Free Software Foundation, Inc.
14 .\"
15 .\" Permission is granted to make and distribute verbatim copies of this
16 .\" manual provided the copyright notice and this permission notice are
17 .\" preserved on all copies.
18 .\"
19 .\" Permission is granted to copy and distribute modified versions of
20 .\" this manual under the conditions for verbatim copying, provided that
21 .\" the entire resulting derived work is distributed under the terms of
22 .\" a permission notice identical to this one.
23 .\"
24 .\" Permission is granted to copy and distribute translations of this
25 .\" manual into another language, under the above conditions for
26 .\" modified versions, except that this permission notice may be
27 .\" included in translations approved by the Free Software Foundation
28 .\" instead of in the original English.
29 .
30 .
31 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
32 .do nr *groff_grn_1_man_C \n[.cp]
33 .cp 0
34 .
35 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
36 .nr do-fallback 0
37 .if !\n(.f .nr do-fallback 1 \" mandoc
38 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
39 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
40 .if \n[do-fallback] \{\
41 . de MR
42 . ie \\n(.$=1 \
43 . I \%\\$1
44 . el \
45 . IR \%\\$1 (\\$2)\\$3
46 . .
47 .\}
48 .rr do-fallback
49 .
50 .
51 .\" ====================================================================
52 .SH Synopsis
53 .\" ====================================================================
54 .
55 .SY \%grn
56 .RB [ \-C ]
57 .RB [ \-T\~\c
58 .IR dev ]
59 .RB [ \-M\~\c
60 .IR dir ]
61 .RB [ \-F\~\c
62 .IR dir ]
63 .RI [ file\~ .\|.\|.]
64 .YS
65 .
66 .
67 .P
68 .SY \%grn
69 .B \-?
70 .YS
71 .
72 .SY \%grn
73 .B \-\-help
74 .YS
75 .
76 .
77 .P
78 .SY \%grn
79 .B \-v
80 .YS
81 .
82 .SY \%grn
83 .B \%\-\-version
84 .YS
85 .
86 .
87 .\" ====================================================================
88 .SH Description
89 .\" ====================================================================
90 .
91 .I \%grn
92 is a preprocessor for including
93 .I gremlin
94 pictures in
95 .MR \%troff 1
96 input.
97 .
98 .I \%grn
99 writes to standard output,
100 processing only input lines between two that start with
101 .B .GS
102 and
103 .BR .GE .
104 .
105 Those lines must contain
106 .I \%grn
107 commands
108 (see below).
109 .
110 These macros request a
111 .I gremlin
112 file;
113 the picture in that file is converted and placed in the
114 .I \%troff
115 input stream.
116 .
117 .B .GS
118 may be called with a
119 .BR C ,
120 .BR L ,
121 or
122 .B R
123 argument to center,
124 left-,
125 or right-align the whole
126 .I gremlin
127 picture
128 (the default is to center).
129 .
130 If no
131 .I file
132 is mentioned,
133 the standard input is read.
134 .
135 At the end of the picture,
136 the position on the page is the bottom of the
137 .I gremlin
138 picture.
139 .
140 If the
141 .I \%grn
142 entry is ended with
143 .B .GF
144 instead of
145 .BR .GE ,
146 the position is left at the top of the picture.
147 .
148 .
149 .PP
150 Currently only the
151 .I me
152 macro package has support for
153 .BR .GS ,
154 .BR .GE ,
155 and
156 .BR .GF .
157 .
158 .
159 .PP
160 .I \%grn
161 produces drawing escape sequences that use
162 .IR groff 's
163 color scheme extension
164 .RB ( \[rs]D\[aq]F \~.\|.\|.\& \[aq] ),
165 and thus may not work with other
166 .IR troff s.
167 .
168 .
169 .\" ====================================================================
170 .SS "\f[I]grn\f[] commands"
171 .\" ====================================================================
172 .
173 Each input line between
174 .B .GS
175 and
176 .B .GE
177 may have one
178 .I \%grn
179 command.
180 .
181 Commands consist of one or two strings separated by whitespace,
182 the first string being the command and the second its operand.
183 .
184 Commands may be upper- or lowercase and abbreviated down to one
185 character.
186 .
187 .
188 .PP
189 Commands that affect a picture's environment
190 (those listed before
191 .RB \%\[lq] default \[rq],
192 see below)
193 are only in effect for the current picture:
194 the environment is reinitialized to the defaults at the start of the
195 next picture.
196 .
197 The commands are as follows.
198 .
199 .
200 .TP
201 .BI 1\~ N
202 .TQ
203 .BI 2\~ N
204 .TQ
205 .BI 3\~ N
206 .TQ
207 .BI 4\~ N
208 .
209 Set
210 .IR gremlin 's
211 text size number 1
212 (2,
213 3,
214 or 4)
215 to
216 .I N
217 points.
218 .
219 The default is 12
220 (16,
221 24,
222 and 36,
223 respectively).
224 .
225 .
226 .TP
227 .BI roman\~ f
228 .TQ
229 .BI italics\~ f
230 .TQ
231 .BI bold\~ f
232 .TQ
233 .BI special\~ f
234 Set the roman
235 (italics,
236 bold,
237 or special)
238 font to
239 .IR \%troff 's
240 font
241 .I f
242 (either a name or number).
243 .
244 The default is R
245 (I,
246 B,
247 and S,
248 respectively).
249 .
250 .
251 .TP
252 .BI l\~ f
253 .TQ
254 .BI stipple\~ f
255 Set the stipple font to
256 .IR \%troff 's
257 stipple font
258 .I f
259 (name or number).
260 .
261 The command
262 .B \%stipple
263 may be abbreviated down as far as
264 .RB \[lq] st \[rq]
265 (to avoid confusion with
266 .RB \%\[lq] special \[rq]).
267 .
268 There is
269 .I no
270 default for stipples
271 (unless one is set by the
272 .RB \%\[lq] default \[rq]
273 command),
274 and it is invalid to include a
275 .I gremlin
276 picture with polygons without specifying a stipple font.
277 .
278 .
279 .TP
280 .BI x\~ N
281 .TQ
282 .BI scale\~ N
283 Magnify the picture
284 (in addition to any default magnification)
285 by
286 .IR N ,
287 a floating-point number larger than zero.
288 .
289 The command
290 .B scale
291 may be abbreviated down to
292 .RB \[lq] sc \[rq].
293 .
294 .
295 .TP
296 .BI narrow\~ N
297 .TQ
298 .BI medium\~ N
299 .TQ
300 .BI thick\~ N
301 .
302 Set the thickness of
303 .IR gremlin 's
304 narrow
305 (medium and thick,
306 respectively)
307 lines to
308 .I N
309 times 0.15pt
310 (this value can be changed at compile time).
311 .
312 The default is 1.0
313 (3.0 and 5.0,
314 respectively),
315 which corresponds to 0.15pt
316 (0.45pt and 0.75pt,
317 respectively).
318 .
319 A thickness value of zero selects the smallest available line thickness.
320 .
321 Negative values cause the line thickness to be proportional to the
322 current point size.
323 .
324 .
325 .TP
326 .BR pointscale\~ [ off | on ]
327 Scale text to match the picture.
328 .
329 Gremlin text is usually printed in the point size specified with the
330 commands
331 .BR 1 ,
332 .BR 2 ,
333 .BR 3 ,
334 .RB or\~ 4 ,
335 regardless of any scaling factors in the picture.
336 .
337 Setting
338 .B pointscale
339 will cause the point sizes to scale with the picture
340 (within
341 .IR \%troff 's
342 limitations,
343 of course).
344 .
345 An operand of anything but
346 .B off
347 will turn text scaling on.
348 .
349 .
350 .TP
351 .B default
352 Reset the picture environment defaults to the settings in the current
353 picture.
354 .
355 This is meant to be used as a global parameter setting mechanism at
356 the beginning of the
357 .I \%troff
358 input,
359 but can be used at any time to reset the default settings.
360 .
361 .
362 .TP
363 .BI width\~ N
364 Force the picture to be
365 .I N
366 inches wide.
367 .
368 This overrides any scaling factors present in the same picture.
369 .
370 .RB \[lq] "width 0" \[rq]
371 is ignored.
372 .
373 .
374 .TP
375 .BI height\~ N
376 Force the picture to be
377 .I N
378 inches high,
379 overriding other scaling factors.
380 .
381 If both
382 .B width
383 and
384 .B height
385 are specified,
386 the tighter constraint will determine the scale of the picture.
387 .
388 .B height
389 and
390 .B width
391 commands are not saved with a
392 .RB \%\[lq] default \[rq]
393 command.
394 .
395 They will,
396 however,
397 affect point size scaling if that option is set.
398 .
399 .
400 .TP
401 .BI file\~ name
402 Get picture from
403 .I gremlin
404 file
405 .I name
406 located the current directory
407 (or in the library directory;
408 see the
409 .B \-M
410 option above).
411 .
412 If multiple
413 .B file
414 commands are given,
415 the last one controls.
416 .
417 If
418 .I name
419 doesn't exist,
420 an error message is reported and processing continues from the
421 .B .GE
422 line.
423 .
424 .
425 .\" ====================================================================
426 .SS "Usage with \f[I]groff\f[]"
427 .\" ====================================================================
428 .
429 Since
430 .I \%grn
431 is a preprocessor,
432 it has no access to elements of formatter state,
433 such as
434 indentation,
435 line length,
436 type size,
437 or
438 register values.
439 .
440 Consequently,
441 no
442 .I \%troff
443 input can be placed between the
444 .B .GS
445 and
446 .B .GE
447 macros.
448 .
449 However,
450 .I gremlin
451 text elements are subsequently processed by
452 .IR \%troff ,
453 so anything valid in a single line of
454 .I \%troff
455 input is valid in a line of
456 .I gremlin
457 text
458 (barring the dot control character \[lq].\[rq] at the beginning of a
459 line).
460 .
461 Thus,
462 it is possible to have equations within a
463 .I gremlin
464 figure by including in the
465 .I gremlin
466 file
467 .I eqn \" language
468 expressions enclosed by previously defined delimiters
469 (e.g.,
470 \[lq]$$\[rq]).
471 .
472 .
473 .PP
474 When using
475 .I \%grn
476 along with other preprocessors,
477 run
478 .MR \%tbl 1
479 before
480 .IR \%grn ,
481 .MR \%pic 1 ,
482 and/or
483 .IR ideal . \" no GNU version yet
484 .
485 If
486 .MR \%eqn 1
487 is needed,
488 run it as the last preprocessor.
489 .
490 .MR groff 1
491 automatically runs preprocessors in the correct order.
492 .
493 .
494 .PP
495 A picture is considered an entity,
496 but that doesn't stop
497 .I \%troff
498 from trying to break it up if it falls off the end of a page.
499 .
500 Placing the picture between \[lq]keeps\[rq] in the
501 .I me
502 macros will ensure proper placement.
503 .
504 .
505 .PP
506 .I \%grn
507 uses
508 .IR \%troff 's
509 registers
510 .B g1
511 through
512 .B g9
513 and sets registers
514 .B g1
515 and
516 .B g2
517 to the width and height of the
518 .I gremlin
519 figure
520 (in device units)
521 before entering the
522 .B .GS
523 macro
524 (this is for those who want to rewrite these macros).
525 .
526 .
527 .\" ====================================================================
528 .SS "Gremlin file format"
529 .\" ====================================================================
530 .
531 There exist two distinct
532 .I gremlin
533 file formats:
534 the original format for AED graphic terminals,
535 and the Sun or X11 version.
536 .
537 An extension used by the Sun/X11 version allowing reference points with
538 negative coordinates is
539 .I not
540 compatible with the AED version.
541 .
542 As long as a
543 .I gremlin
544 file does not contain negative coordinates,
545 either format will be read correctly by either version of
546 .I gremlin
547 or
548 .IR \%grn .
549 .
550 The other difference in
551 Sun/X11 format is the use of names for picture objects
552 (e.g.,
553 .BR POLYGON ,
554 .BR CURVE )
555 instead of numbers.
556 .
557 Files representing the same picture are shown below.
558 .
559 .
560 .PP
561 .EX
562 .ie t .ne 18v
563 .el .ne 19v
564 .TS
565 center, tab(@);
566 l lw(0.1i) l.
567 sungremlinfile@@gremlinfile
568 0 240.00 128.00@@0 240.00 128.00
569 CENTCENT@@2
570 240.00 128.00@@240.00 128.00
571 185.00 120.00@@185.00 120.00
572 240.00 120.00@@240.00 120.00
573 296.00 120.00@@296.00 120.00
574 *@@\-1.00 \-1.00
575 2 3@@2 3
576 10 A Triangle@@10 A Triangle
577 POLYGON@@6
578 224.00 416.00@@224.00 416.00
579 96.00 160.00@@96.00 160.00
580 384.00 160.00@@384.00 160.00
581 *@@\-1.00 \-1.00
582 5 1@@5 1
583 0@@0
584 \-1@@\-1
585 .TE
586 .EE
587 .
588 .
589 .IP \[bu] 3n
590 The first line of each
591 .I gremlin
592 file contains either the string
593 .RB \%\[lq] gremlinfile \[rq]
594 (AED)
595 or
596 .RB \%\[lq] sungremlinfile \[rq]
597 (Sun/X11).
598 .
599 .
600 .IP \[bu]
601 The second line of the file contains an orientation and
602 .I x
603 and
604 .I y
605 values for a positioning point,
606 separated by spaces.
607 .
608 The orientation,
609 either
610 .B 0
611 or
612 .BR 1 ,
613 is ignored by the Sun/X11 version.
614 .
615 .B 0
616 means that
617 .I gremlin
618 will display things in horizontal format
619 (a drawing area wider than it is tall,
620 with a menu across the top).
621 .
622 .B 1
623 means that
624 .I gremlin
625 will display things in vertical format
626 (a drawing area taller than it is wide,
627 with a menu on the left side).
628 .
629 .I x
630 and
631 .I y
632 are floating-point values giving a positioning point to be used when
633 this file is read into another file.
634 .
635 The stuff on this line really isn't all that important;
636 a value of
637 .RB \[lq] "1 0.00 0.00" \[rq]
638 is suggested.
639 .
640 .
641 .IP \[bu]
642 The rest of the file consists of zero or more element specifications.
643 .
644 After the last element specification is a line containing the string
645 .RB \[lq] \-1 \[rq].
646 .
647 .
648 .IP \[bu]
649 Lines longer than 127 characters are truncated to that length.
650 .
651 .
652 .\" ====================================================================
653 .SS "Element specifications"
654 .\" ====================================================================
655 .
656 .IP \[bu] 3n
657 The first line of each element contains a single decimal number giving
658 the type of the element (AED) or its name (Sun/X11).
659 .
660 .
661 .IP
662 .ie t .ne 18v
663 .el .ne 19v
664 .TS
665 center, tab(@);
666 css
667 ccc
668 nBlBl.
669 \f[I]gremlin\f[] File Format: Object Type Specification
670 _
671 AED Number@Sun/X11 Name@Description
672 0@BOTLEFT@text aligned to bottom left
673 1@BOTRIGHT@text aligned to bottom right
674 2@CENTCENT@center object
675 3@VECTOR@vector
676 4@ARC@arc
677 5@CURVE@curve
678 6@POLYGON@polygon
679 7@BSPLINE@b-spline
680 8@BEZIER@B\['e]zier
681 10@TOPLEFT@text aligned to top left
682 11@TOPCENT@text aligned to top center
683 12@TOPRIGHT@text aligned to top right
684 13@CENTLEFT@text aligned to center left
685 14@CENTRIGHT@text aligned to center right
686 15@BOTCENT@text aligned to bottom center
687 .TE
688 .
689 .
690 .IP \[bu]
691 Each line after the object type specifies a point used to display the
692 element.
693 .
694 It contains an
695 .I x
696 and a
697 .I y
698 coordinate in floating-point format,
699 separated by spaces.
700 .
701 The list of points is terminated by a line containing the string
702 .RB \[lq] "\-1.0 \-1.0" \[rq]
703 (AED) or a single asterisk,
704 .RB \[lq] * \[rq]
705 (Sun/X11).
706 .
707 .
708 .IP \[bu]
709 After the points comes a line containing two decimal values,
710 giving the brush and size for the element.
711 .
712 The brush determines the style in which things are drawn.
713 .
714 For vectors,
715 arcs,
716 and curves there are six valid brush values.
717 .
718 .
719 .IP
720 .TS
721 center, tab(@);
722 nB l.
723 1@thin dotted lines
724 2@thin dot-dashed lines
725 3@thick solid lines
726 4@thin dashed lines
727 5@thin solid lines
728 6@medium solid lines
729 .TE
730 .
731 .
732 .IP
733 For polygons,
734 0
735 is also valid:
736 it specifies an invisible border.
737 .
738 For text,
739 the brush selects a font as follows.
740 .
741 .
742 .IP
743 .TS
744 center, tab(@);
745 nB l.
746 1@roman (R font in \f[I]\%troff\f[])
747 2@italics (I font in \f[I]\%troff\f[])
748 3@bold (B font in \f[I]\%troff\f[])
749 4@special (S font in \f[I]\%troff\f[])
750 .TE
751 .
752 .
753 .IP
754 If you're using
755 .I \%grn
756 to run your pictures through
757 .IR groff ,
758 the font is really just a starting font.
759 .
760 The text string can contain formatting sequences like
761 \[lq]\[rs]fI\[rq]
762 or
763 \[lq]\[rs]d\[rq]
764 which may change the font
765 (as well as do many other things).
766 .
767 For text,
768 the size field is a decimal value between 1 and 4.
769 .
770 It selects the size of the font in which the text will be drawn.
771 .
772 For polygons,
773 this size field is interpreted as a stipple number to fill the polygon
774 with.
775 .
776 The number is used to index into a stipple font at print time.
777 .
778 .
779 .IP \[bu]
780 The last line of each element contains a decimal number and a string of
781 characters,
782 separated by a single space.
783 .
784 The number is a count of the number of characters in the string.
785 .
786 This information is used only for text elements,
787 and contains the text string.
788 .
789 There can be spaces inside the text.
790 .
791 For arcs,
792 curves,
793 and vectors,
794 the character count is zero
795 .RB ( 0 ),
796 followed by exactly one space before the newline.
797 .
798 .
799 .\" ====================================================================
800 .SS Coordinates
801 .\" ====================================================================
802 .
803 .I gremlin
804 was designed for AED terminals,
805 and its coordinates reflect the AED coordinate space.
806 .
807 For vertical pictures,
808 .IR x \~values
809 range 116 to 511,
810 and
811 .IR y \~values
812 from 0 to 483.
813 .
814 For horizontal pictures,
815 .IR x \~values
816 range from 0 to 511,
817 and
818 .IR y \~values
819 from 0 to 367.
820 .
821 Although you needn't absolutely stick to this range,
822 you'll get better results if you at least stay in this vicinity.
823 .
824 Also,
825 point lists are terminated by a point of
826 (\-1,
827 \-1),
828 so you shouldn't ever use negative coordinates.
829 .
830 .I gremlin
831 writes out coordinates using the
832 .MR printf 3
833 format \[lq]%f1.2\[rq];
834 it's probably a good idea to use the same format if you want to modify
835 the
836 .I \%grn
837 code.
838 .
839 .
840 .\" ====================================================================
841 .SS "Sun/X11 coordinates"
842 .\" ====================================================================
843 .
844 There is no restriction on the range of coordinates used to create
845 objects in the Sun/X11 version of
846 .IR gremlin .
847 .
848 However,
849 files with negative coordinates
850 .I will
851 cause problems if displayed on the AED.
852 .
853 .
854 .\" ====================================================================
855 .SH Options
856 .\" ====================================================================
857 .
858 .B \-?\&
859 and
860 .B \-\-help
861 display a usage message,
862 while
863 .B \-v
864 and
865 .B \%\-\-version
866 show version information;
867 all exit afterward.
868 .
869 .
870 .TP 8.125n \" "-F dir" + 2n + hand-tuned for PDF
871 .B \-C
872 Recognize
873 .B .GS
874 and
875 .B .GE
876 (and
877 .BR .GF )
878 even when followed by a character other than space or newline.
879 .
880 .
881 .TP
882 .BI \-F\~ dir
883 Search
884 .I dir
885 for subdirectories
886 .IR dev name
887 .RI ( name
888 is the name of the output driver)
889 for the
890 .I DESC
891 file before the default font directories
892 .IR /usr/\:\%share/\:\%groff/\:\%site\-font ,
893 .IR /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font ,
894 and
895 .IR /usr/\:\%lib/\:\%font .
896 .
897 .
898 .TP
899 .BI \-M\~ dir
900 Prepend
901 .I dir
902 to the search path for
903 .I gremlin
904 files.
905 .
906 The default search path is the current directory,
907 the home directory,
908 .if !'no'no' .IR /usr/\:\%lib/\:\%groff/\:\%site\-tmac ,
909 .IR /usr/\:\%share/\:\%groff/\:\%site\-tmac ,
910 and
911 .IR /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac ,
912 in that order.
913 .\".
914 .\".
915 .\".TP
916 .\".B \-s
917 .\"This switch causes the picture to be traversed twice:
918 .\"The first time,
919 .\"only the interiors of filled polygons
920 .\"(as borderless polygons)
921 .\"are printed.
922 .\".
923 .\"The second time,
924 .\"the outline is printed as a series of line segments.
925 .\".
926 .\"This way,
927 .\"postprocessors that overwrite rather than merge picture elements
928 .\"(such as PostScript)
929 .\"can still have text and graphics on a shaded background.
930 .
931 .
932 .TP
933 .BI \-T\~ dev
934 Prepare device output using output driver
935 .IR dev .
936 .
937 The default is
938 .BR \%ps .
939 .
940 See
941 .MR groff 1
942 for a list of valid devices.
943 .
944 .
945 .\" ====================================================================
946 .SH "Exit status"
947 .\" ====================================================================
948 .
949 .I \%grn
950 exits with
951 .RB status\~ 0
952 on successful operation,
953 .RB status\~ 2
954 if the program cannot interpret its command-line arguments,
955 and
956 .RB status\~ 1
957 if it encounters an error during operation.
958 .
959 .
960 .\" ====================================================================
961 .SH Files
962 .\" ====================================================================
963 .
964 .TP
965 .IR /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%dev name /\:DESC
966 describes the output device
967 .IR name .
968 .
969 .
970 .\" ====================================================================
971 .SH Authors
972 .\" ====================================================================
973 .
974 David Slattengren and Barry Roitblat wrote the original Berkeley
975 .IR grn .
976 .
977 Daniel Senderowicz and
978 .MT wl@\:gnu\:.org
979 Werner Lemberg
980 .ME
981 modified it for
982 .IR groff .
983 .
984 .
985 .\" ====================================================================
986 .SH "See also"
987 .\" ====================================================================
988 .
989 .MR gremlin 1 ,
990 .MR groff 1 ,
991 .MR \%pic 1 ,
992 .MR ideal 1
993 .
994 .
995 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
996 .cp \n[*groff_grn_1_man_C]
997 .do rr *groff_grn_1_man_C
998 .
999 .
1000 .\" Local Variables:
1001 .\" fill-column: 72
1002 .\" mode: nroff
1003 .\" End:
1004 .\" vim: set filetype=groff textwidth=72: