Debian Codegraph @

upstream/debian-trixie/man1/grn.1

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