Debian Codegraph @

upstream/debian-trixie/man1/grops.1

raw
1 .TH grops 1 "3 June 2025" "groff 1.23.0"
2 .SH Name
3 grops \-
4 .I groff
5 output driver for PostScript
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright (C) 1989-2018, 2020 Free Software Foundation, Inc.
13 .\"
14 .\" Permission is granted to make and distribute verbatim copies of this
15 .\" manual provided the copyright notice and this permission notice are
16 .\" preserved on all copies.
17 .\"
18 .\" Permission is granted to copy and distribute modified versions of
19 .\" this manual under the conditions for verbatim copying, provided that
20 .\" the entire resulting derived work is distributed under the terms of
21 .\" a permission notice identical to this one.
22 .\"
23 .\" Permission is granted to copy and distribute translations of this
24 .\" manual into another language, under the above conditions for
25 .\" modified versions, except that this permission notice may be
26 .\" included in translations approved by the Free Software Foundation
27 .\" instead of in the original English.
28 .
29 .
30 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
31 .do nr *groff_grops_1_man_C \n[.cp]
32 .cp 0
33 .
34 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
35 .nr do-fallback 0
36 .if !\n(.f .nr do-fallback 1 \" mandoc
37 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
38 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
39 .if \n[do-fallback] \{\
40 . de MR
41 . ie \\n(.$=1 \
42 . I \%\\$1
43 . el \
44 . IR \%\\$1 (\\$2)\\$3
45 . .
46 .\}
47 .rr do-fallback
48 .
49 .
50 .\" This macro definition is poor style from a portability standpoint,
51 .\" but it's a good test and demonstration of the standard font
52 .\" repertoire for the devices where it has any effect at all, and so
53 .\" should be retained.
54 .de FT
55 . if '\\*(.T'ps' .ft \\$1
56 . if '\\*(.T'pdf' .ft \\$1
57 ..
58 .
59 .\" ====================================================================
60 .SH Synopsis
61 .\" ====================================================================
62 .
63 .SY grops
64 .RB [ \-glm ]
65 .RB [ \-b\~\c
66 .IR brokenness-flags ]
67 .RB [ \-c\~\c
68 .IR num-copies ]
69 .RB [ \-F\~\c
70 .IR font-directory ]
71 .RB [ \-I\~\c
72 .IR inclusion-directory ]
73 .RB [ \-p\~\c
74 .IR paper-format ]
75 .RB [ \-P\~\c
76 .IR prologue-file ]
77 .RB [ \-w\~\c
78 .IR rule-thickness ]
79 .RI [ file\~ .\|.\|.]
80 .YS
81 .
82 .
83 .SY grops
84 .B \-\-help
85 .YS
86 .
87 .
88 .SY grops
89 .B \-v
90 .
91 .SY grops
92 .B \-\-version
93 .YS
94 .
95 .
96 .\" ====================================================================
97 .SH Description
98 .\" ====================================================================
99 .
100 The GNU
101 .I roff
102 PostScript output driver translates the output of
103 .MR \%troff 1
104 into PostScript.
105 .
106 Normally,
107 .I grops
108 is invoked by
109 .MR groff 1
110 when the latter is given the
111 .RB \[lq] \-T\~ps \[rq]
112 option.
113 .
114 (In this installation,
115 .B \%ps
116 is the default output device.)
117 .
118 Use
119 .IR groff 's
120 .B \-P
121 option to pass any options shown above to
122 .IR grops .
123 .
124 If no
125 .I file
126 arguments are given,
127 or if
128 .I file
129 is \[lq]\-\[rq],
130 .I grotty
131 reads the standard input stream.
132 .
133 Output is written to the standard output stream.
134 .
135 .
136 .P
137 When called with multiple
138 .I file
139 arguments,
140 .I grops
141 doesn't produce a valid document structure
142 (one conforming to the Document Structuring Conventions).
143 .
144 To print such concatenated output,
145 it is necessary to deactivate DSC handling in the printing program or
146 previewer.
147 .
148 .
149 .P
150 See section \[lq]Font installation\[rq] below for a guide to installing
151 fonts for
152 .IR grops .
153 .
154 .
155 .\" ====================================================================
156 .SH Options
157 .\" ====================================================================
158 .
159 .B \-\-help
160 displays a usage message,
161 while
162 .B \-v
163 and
164 .B \-\-version
165 show version information;
166 all exit afterward.
167 .
168 .
169 .TP
170 .BI \-b\~ n
171 Work around problems with spoolers,
172 previewers,
173 and older printers.
174 .
175 Normally,
176 .I grops
177 produces output at PostScript \%LanguageLevel\~2 that conforms to
178 version 3.0 of the Document Structuring Conventions.
179 .
180 Some software and devices can't handle such a data stream.
181 .
182 The value
183 .RI of\~ n
184 determines what
185 .I grops
186 does to make its output acceptable to such consumers.
187 .
188 If
189 .I n
190 is
191 .BR 0 ,
192 .I grops
193 employs no workarounds,
194 which is the default;
195 it can be changed by modifying the
196 .B broken
197 directive in
198 .IR grops 's
199 .I DESC
200 file.
201 .
202 .
203 .IP
204 Add\~1 to suppress generation of
205 .B %%Begin\%Document\%Setup
206 and
207 .B %%End\%Document\%Setup
208 comments;
209 this is needed for early versions of TranScript that get confused by
210 anything between the
211 .B %%End\%Prolog
212 comment and the first
213 .B %%Page
214 comment.
215 .
216 .
217 .IP
218 Add\~2 to omit lines in included files beginning with
219 .BR %!\& ,
220 which confuse Sun's
221 .I pageview
222 previewer.
223 .
224 .
225 .IP
226 Add\~4 to omit lines in included files beginning with
227 .BR %%Page ,
228 .B %%Trailer
229 and
230 .BR %%End\%Prolog ;
231 this is needed for spoolers that don't understand
232 .B %%Begin\%Document
233 and
234 .B %%End\%Document
235 comments.
236 .
237 .
238 .IP
239 Add\~8 to write
240 .B %!PS\-Adobe\-2.0
241 rather than
242 .B %!PS\-Adobe\-3.0
243 as the first line of the PostScript output;
244 this is needed when using Sun's Newsprint with a printer that requires
245 page reversal.
246 .
247 .
248 .IP
249 Add\~16 to omit media size information
250 (that is,
251 output neither a
252 .B %%Document\%Media
253 comment nor the
254 .B setpagedevice
255 PostScript command).
256 .
257 This was the behavior of
258 .I groff
259 1.18.1 and earlier;
260 it is
261 needed for older printers that don't understand PostScript
262 \%LanguageLevel\~2,
263 and is also necessary if the output is further processed to produce an
264 EPS file;
265 see subsection \[lq]Escapsulated PostScript\[rq] below.
266 .
267 .
268 .TP
269 .BI \-c\~ n
270 Output
271 .I n
272 copies of each page.
273 .
274 .
275 .TP
276 .BI \-F\~ dir
277 Prepend directory
278 .RI dir /dev name
279 to the search path for
280 font and device description and PostScript prologue files;
281 .I name
282 is the name of the device,
283 usually
284 .BR ps .
285 .
286 .
287 .TP
288 .B \-g
289 Generate PostScript code to guess the page length.
290 .
291 The guess is correct only if the imageable area is vertically centered
292 on the page.
293 .
294 This option allows you to generate documents that can be printed on both
295 U.S.\& letter and A4 paper formats without change.
296 .
297 .
298 .TP
299 .BI \-I\~ dir
300 Search the directory
301 .I dir
302 for files named in
303 .B \[rs]X\[aq]ps: file\[aq]
304 and
305 .B \[rs]X\[aq]ps: import\[aq]
306 escape sequences.
307 .
308 .B \-I
309 may be specified more than once;
310 each
311 .I dir
312 is searched in the given order.
313 .
314 To search the current working directory before others,
315 add
316 .RB \[lq] "\-I .\&" \[rq]
317 at the desired place;
318 it is otherwise searched last.
319 .
320 .
321 .TP
322 .B \-l
323 Use landscape orientation rather than portrait.
324 .
325 .
326 .TP
327 .B \-m
328 Turn on manual feed for the document.
329 .
330 .
331 .TP
332 .BI \-p\~ fmt
333 Set physical dimensions of output medium,
334 overriding the
335 .BR \%papersize ,
336 .BR \%paperlength ,
337 and
338 .B \%paperwidth
339 directives in the
340 .I DESC
341 file.
342 .
343 .I fmt
344 can be any argument accepted by the
345 .B \%papersize
346 directive;
347 see
348 .MR groff_font 5 .
349 .
350 .
351 .TP
352 .BI \-P\~ prologue
353 Use the file
354 .IR prologue ,
355 sought in the
356 .I groff
357 font search path,
358 as the PostScript prologue,
359 overriding the default
360 (see section \[lq]Files\[rq] below)
361 and the environment variable
362 .I GROPS_PROLOGUE.
363 .
364 .
365 .TP
366 .BI \-w\~ n
367 Draw rules (lines) with a thickness of
368 .IR n \~thousandths
369 of an em.
370 .
371 The default thickness is
372 .B 40
373 (0.04\~em).
374 .
375 .
376 .\" ====================================================================
377 .SH Usage
378 .\" ====================================================================
379 .
380 The input to
381 .I grops
382 must be in the format output by
383 .MR \%troff 1 ,
384 described in
385 .MR groff_out 5 .
386 .
387 In addition,
388 the device and font description files for the device used must meet
389 certain requirements.
390 .
391 The device resolution must be an integer multiple of\~72 times the
392 .BR sizescale .
393 .
394 The device description file must contain a valid paper format;
395 see
396 .MR groff_font 5 .
397 .
398 Each font description file must contain a directive
399 .
400 .RS
401 .EX
402 .RI internalname\~ psname
403 .EE
404 .RE
405 .
406 which says that the PostScript name of the font is
407 .IR psname .
408 .
409 .
410 .P
411 A font description file may also contain a directive
412 .
413 .RS
414 .EX
415 .RI encoding\~ enc-file
416 .EE
417 .RE
418 .
419 which says that
420 the PostScript font should be reencoded using the encoding described in
421 .IR enc-file ;
422 this file should consist of a sequence of lines of the form
423 .
424 .
425 .RS
426 .EX
427 .I pschar code
428 .EE
429 .RE
430 .
431 where
432 .I pschar
433 is the PostScript name of the character,
434 and
435 .I code
436 is its position in the encoding expressed as a decimal integer;
437 valid values are in the range 0 to\~255.
438 .
439 Lines starting with
440 .B #
441 and blank lines are ignored.
442 .
443 The code for each character given in the font description file must
444 correspond to the code for the character in encoding file,
445 or to the code in the default encoding for the font if the PostScript
446 font is not to be reencoded.
447 .
448 This code can be used with the
449 .B \[rs]N
450 escape sequence in
451 .I \%troff
452 to select the character,
453 even if it does not have a
454 .I groff
455 glyph name.
456 .
457 Every character in the font description file must exist in the
458 PostScript font,
459 and the widths given in the font description file must match the widths
460 used in the PostScript font.
461 .
462 .I grops
463 assumes that a character with a
464 .I groff
465 name of
466 .B space
467 is blank
468 (makes no marks on the page);
469 it can make use of such a character to generate more efficient and
470 compact PostScript output.
471 .
472 .
473 .P
474 .I grops
475 is able to display all glyphs in a PostScript font;
476 it is not limited to 256 of them.
477 .
478 .I enc-file
479 (or the default encoding if no encoding file is specified)
480 just defines the
481 order of glyphs for the first 256 characters;
482 all other glyphs are accessed with additional encoding vectors which
483 .I grops
484 produces on the fly.
485 .
486 .
487 .P
488 .I grops
489 can embed fonts in a document that are necessary to render it;
490 this is called \[lq]downloading\[rq].
491 .
492 Such fonts must be in PFA format.
493 .
494 Use
495 .MR pfbtops 1
496 to convert a Type\~1 font in PFB format.
497 .
498 Downloadable fonts must be listed a
499 .I download
500 file containing lines of the form
501 .
502 .RS
503 .EX
504 .I psname file
505 .EE
506 .RE
507 .
508 where
509 .I psname
510 is the PostScript name of the font,
511 and
512 .I file
513 is the name of the file containing it;
514 lines beginning with
515 .B #
516 and blank lines are ignored;
517 fields may be separated by tabs or spaces.
518 .
519 .I file
520 is sought using the same mechanism as that for
521 .I groff
522 font description files.
523 .
524 The
525 .I download
526 file itself is also sought using this mechanism;
527 currently,
528 only the first matching file found in the device and font description
529 search path is used.
530 .
531 .
532 .P
533 If the file containing a downloadable font or imported document
534 conforms to the Adobe Document Structuring Conventions,
535 then
536 .I grops
537 interprets any comments in the files sufficiently to ensure that its
538 own output is conforming.
539 .
540 It also supplies any needed font resources that are listed in the
541 .I download
542 file
543 as well as any needed file resources.
544 .
545 It is also able to handle inter-resource dependencies.
546 .
547 For example,
548 suppose that you have a downloadable font called Garamond,
549 and also a downloadable font called Garamond-Outline which depends on
550 Garamond
551 (typically it would be defined to copy Garamond's font dictionary,
552 and change the PaintType),
553 then it is necessary for Garamond to appear before Garamond-Outline in
554 the PostScript document.
555 .
556 .I grops
557 handles this automatically provided that the downloadable font file
558 for Garamond-Outline indicates its dependence on Garamond by means of
559 the Document Structuring Conventions,
560 for example by beginning with the following lines.
561 .
562 .RS
563 .EX
564 %!PS\-Adobe\-3.0 Resource\-Font
565 %%DocumentNeededResources: font Garamond
566 %%EndComments
567 %%IncludeResource: font Garamond
568 .EE
569 .RE
570 .
571 In this case,
572 both Garamond and Garamond-Outline would need to be listed
573 in the
574 .I download
575 file.
576 .
577 A downloadable font should not include its own name in a
578 .B %%Document\%Supplied\%Resources
579 comment.
580 .
581 .
582 .P
583 .I grops
584 does not interpret
585 .B %%Document\%Fonts
586 comments.
587 .
588 The
589 .BR %%Document\%Needed\%Resources ,
590 .BR %%Document\%Supplied\%Resources ,
591 .BR %%Include\%Resource ,
592 .BR %%Begin\%Resource ,
593 and
594 .B %%End\%Resource
595 comments
596 (or possibly the old
597 .BR %%Document\%Needed\%Fonts ,
598 .BR %%Document\%Supplied\%Fonts ,
599 .BR %%Include\%Font ,
600 .BR %%Begin\%Font ,
601 and
602 .B %%End\%Font
603 comments)
604 should be used.
605 .
606 .
607 .P
608 The default stroke and fill color is black.
609 .
610 For colors defined in the \[lq]rgb\[rq] color space,
611 .B setrgbcolor
612 is used;
613 for \[lq]cmy\[rq] and \[lq]cmyk\[rq],
614 .BR setcmykcolor ;
615 and for \[lq]gray\[rq],
616 .BR setgray .
617 .
618 .B setcmykcolor
619 is a PostScript \%LanguageLevel\~2 command and thus not available on
620 some older printers.
621 .
622 .
623 .\" ====================================================================
624 .SS Typefaces
625 .\" ====================================================================
626 .
627 .P
628 Styles called
629 .BR R ,
630 .BR I ,
631 .BR B ,
632 and
633 .B BI
634 mounted at font positions 1 to\~4.
635 .
636 Text fonts are grouped into families
637 .BR A ,
638 .BR BM ,
639 .BR C ,
640 .BR H ,
641 .BR HN ,
642 .BR N ,
643 .BR P ,
644 .RB and\~ T ,
645 each having members in each of these styles.
646 .
647 .
648 .RS
649 .TP
650 .B AR
651 .FT AR
652 AvantGarde-Book
653 .FT
654 .
655 .TQ
656 .B AI
657 .FT AI
658 AvantGarde-BookOblique
659 .FT
660 .
661 .TQ
662 .B AB
663 .FT AB
664 AvantGarde-Demi
665 .FT
666 .
667 .TQ
668 .B ABI
669 .FT ABI
670 AvantGarde-DemiOblique
671 .FT
672 .
673 .TQ
674 .B BMR
675 .FT BMR
676 Bookman-Light
677 .FT
678 .
679 .TQ
680 .B BMI
681 .FT BMI
682 Bookman-LightItalic
683 .FT
684 .
685 .TQ
686 .B BMB
687 .FT BMB
688 Bookman-Demi
689 .FT
690 .
691 .TQ
692 .B BMBI
693 .FT BMBI
694 Bookman-DemiItalic
695 .FT
696 .
697 .TQ
698 .B CR
699 .FT CR
700 Courier
701 .FT
702 .
703 .TQ
704 .B CI
705 .FT CI
706 Courier-Oblique
707 .FT
708 .
709 .TQ
710 .B CB
711 .FT CB
712 Courier-Bold
713 .FT
714 .
715 .TQ
716 .B CBI
717 .FT CBI
718 Courier-BoldOblique
719 .FT
720 .
721 .TQ
722 .B HR
723 .FT HR
724 Helvetica
725 .FT
726 .
727 .TQ
728 .B HI
729 .FT HI
730 Helvetica-Oblique
731 .FT
732 .
733 .TQ
734 .B HB
735 .FT HB
736 Helvetica-Bold
737 .FT
738 .
739 .TQ
740 .B HBI
741 .FT HBI
742 Helvetica-BoldOblique
743 .FT
744 .
745 .TQ
746 .B HNR
747 .FT HNR
748 Helvetica-Narrow
749 .FT
750 .
751 .TQ
752 .B HNI
753 .FT HNI
754 Helvetica-Narrow-Oblique
755 .FT
756 .
757 .TQ
758 .B HNB
759 .FT HNB
760 Helvetica-Narrow-Bold
761 .FT
762 .
763 .TQ
764 .B HNBI
765 .FT HNBI
766 Helvetica-Narrow-BoldOblique
767 .FT
768 .
769 .TQ
770 .B NR
771 .FT NR
772 NewCenturySchlbk-Roman
773 .FT
774 .
775 .TQ
776 .B NI
777 .FT NI
778 NewCenturySchlbk-Italic
779 .FT
780 .
781 .TQ
782 .B NB
783 .FT NB
784 NewCenturySchlbk-Bold
785 .FT
786 .
787 .TQ
788 .B NBI
789 .FT NBI
790 NewCenturySchlbk-BoldItalic
791 .FT
792 .
793 .TQ
794 .B PR
795 .FT PR
796 Palatino-Roman
797 .FT
798 .
799 .TQ
800 .B PI
801 .FT PI
802 Palatino-Italic
803 .FT
804 .
805 .TQ
806 .B PB
807 .FT PB
808 Palatino-Bold
809 .FT
810 .
811 .TQ
812 .B PBI
813 .FT PBI
814 Palatino-BoldItalic
815 .FT
816 .
817 .TQ
818 .B TR
819 .FT TR
820 Times-Roman
821 .FT
822 .
823 .TQ
824 .B TI
825 .FT TI
826 Times-Italic
827 .FT
828 .
829 .TQ
830 .B TB
831 .FT TB
832 Times-Bold
833 .FT
834 .
835 .TQ
836 .B TBI
837 .FT TBI
838 Times-BoldItalic
839 .FT
840 .RE
841 .
842 .
843 .br
844 .ne 2v
845 .P
846 Another text font is not a member of a family.
847 .
848 .
849 .RS
850 .TP
851 .B ZCMI
852 .FT ZCMI
853 ZapfChancery-MediumItalic
854 .FT
855 .RE
856 .
857 .
858 .P
859 Special fonts include
860 .BR S ,
861 the PostScript Symbol font;
862 .BR ZD ,
863 Zapf Dingbats;
864 .B SS
865 (slanted symbol),
866 which contains oblique forms of lowercase Greek letters derived from
867 Symbol;
868 .BR EURO ,
869 which offers a Euro glyph for use with old devices lacking it;
870 and
871 .BR ZDR ,
872 a reversed version of ZapfDingbats
873 (with symbols flipped about the vertical axis).
874 .
875 Most glyphs in these fonts are unnamed and must be accessed using
876 .BR \[rs]N .
877 .
878 The last three are not standard PostScript fonts,
879 but supplied by
880 .I groff
881 and therefore included in the default
882 .I download
883 file.
884 .
885 .
886 .\" ====================================================================
887 .SS "Device control commands"
888 .\" ====================================================================
889 .
890 .I grops
891 recognizes device control commands produced by the
892 .B \[rs]X
893 escape sequence,
894 but interprets only those that begin with a
895 .RB \[lq] ps: \[rq]
896 tag.
897 .
898 .
899 .TP
900 .BI "\[rs]X\[aq]ps: exec\~" code \[aq]
901 .RS
902 Execute the arbitrary PostScript commands
903 .IR code .
904 .
905 The PostScript
906 .I \%currentpoint
907 is set to the
908 .I groff
909 drawing position when the
910 .B \[rs]X
911 escape sequence is interpreted before executing
912 .IR code .
913 .
914 The origin is at the top left corner of the page;
915 .IR x \~coordinates
916 increase to the right,
917 and
918 .IR y \~coordinates
919 down the page.
920 .
921 A
922 .RB procedure\~ u
923 is defined that converts
924 .I groff
925 basic units to the coordinate system in effect
926 (provided the user doesn't change the scale).
927 .
928 For example,
929 .
930 .RS
931 .EX
932 \&.nr x 1i
933 \[rs]X\[aq]ps: exec \[rs]nx u 0 rlineto stroke\[aq]
934 .EE
935 .RE
936 .
937 draws a horizontal line one inch long.
938 .
939 .I code
940 may make changes to the graphics state,
941 but any changes persist only to the end of the page.
942 .
943 A dictionary containing the definitions specified by the
944 .B def
945 and
946 .B mdef
947 commands is on top of the dictionary stack.
948 .
949 If your code adds definitions to this dictionary,
950 you should allocate space for them using
951 .RB \[lq] "\[rs]X\[aq]ps: mdef\~"
952 .IB n \[aq]\c
953 \[rq].
954 .
955 Any definitions persist only until the end of the page.
956 .
957 If you use the
958 .B \[rs]Y
959 escape sequence with an argument that names a macro,
960 .I code
961 can extend over multiple lines.
962 .
963 For example,
964 .
965 .RS
966 .EX
967 \&.nr x 1i
968 \&.de y
969 \&ps: exec
970 \&\[rs]nx u 0 rlineto
971 \&stroke
972 \&..
973 \&\[rs]Yy
974 .EE
975 .RE
976 .
977 is another way to draw a horizontal line one inch long.
978 .
979 The single backslash before
980 .RB \[lq] nx \[rq]\[em]the
981 only reason to use a register while defining the macro
982 .RB \[lq] y \[rq]\[em]is
983 to convert a user-specified dimension
984 .RB \[lq] 1i \[rq]
985 to
986 .I groff
987 basic units which are in turn converted to PostScript units with the
988 .B u
989 procedure.
990 .
991 .
992 .P
993 .I grops
994 wraps user-specified PostScript code into a dictionary,
995 nothing more.
996 .
997 In particular,
998 it doesn't start and end the inserted code with
999 .B save
1000 and
1001 .BR restore ,
1002 respectively.
1003 .
1004 This must be supplied by the user,
1005 if necessary.
1006 .RE
1007 .
1008 .
1009 .TP
1010 .BI "\[rs]X\[aq]ps: file\~" name \[aq]
1011 This is the same as the
1012 .B exec
1013 command except that the PostScript code is read from file
1014 .IR name .
1015 .
1016 .
1017 .TP
1018 .BI "\[rs]X\[aq]ps: def\~" code \[aq]
1019 Place a PostScript definition contained in
1020 .I code
1021 in the prologue.
1022 .
1023 There should be at most one definition per
1024 .B \[rs]X
1025 command.
1026 .
1027 Long definitions can be split over several
1028 .B \[rs]X
1029 commands;
1030 all the
1031 .I code
1032 arguments are simply joined together separated by newlines.
1033 .
1034 The definitions are placed in a dictionary which is automatically
1035 pushed on the dictionary stack when an
1036 .B exec
1037 command is executed.
1038 .
1039 If you use the
1040 .B \[rs]Y
1041 escape sequence with an argument that names a macro,
1042 .I code
1043 can extend over multiple lines.
1044 .
1045 .
1046 .TP
1047 .BI "\[rs]X\[aq]ps: mdef\~" "n code" \[aq]
1048 Like
1049 .BR def ,
1050 except that
1051 .I code
1052 may contain up to
1053 .IR n \~definitions.
1054 .
1055 .I grops
1056 needs to know how many definitions
1057 .I code
1058 contains
1059 so that it can create an appropriately sized PostScript dictionary
1060 to contain them.
1061 .
1062 .
1063 .TP
1064 .BI "\[rs]X\[aq]ps: import\~" "file llx lly urx ury width\~"\c
1065 .RI [ height ]\c
1066 .B \[aq]
1067 Import a PostScript graphic from
1068 .IR file .
1069 .
1070 The arguments
1071 .IR llx ,
1072 .IR lly ,
1073 .IR urx ,
1074 and
1075 .I ury
1076 give the bounding box of the graphic in the default PostScript
1077 coordinate system.
1078 .
1079 They should all be integers:
1080 .I llx
1081 and
1082 .I lly
1083 are the
1084 .I x
1085 and
1086 .IR y \~coordinates
1087 of the lower left corner of the graphic;
1088 .I urx
1089 and
1090 .I ury
1091 are the
1092 .I x
1093 and
1094 .IR y \~coordinates
1095 of the upper right corner of the graphic;
1096 .I width
1097 and
1098 .I height
1099 are integers that give the desired width and height in
1100 .I groff
1101 basic units of the graphic.
1102 .
1103 .
1104 .IP
1105 The graphic is scaled so that it has this width and height
1106 and translated so that the lower left corner of the graphic is
1107 located at the position associated with
1108 .B \[rs]X
1109 command.
1110 .
1111 If the height argument is omitted it is scaled uniformly in the
1112 .I x
1113 and
1114 .IR y \~axes
1115 so that it has the specified width.
1116 .
1117 .
1118 .IP
1119 The contents of the
1120 .B \[rs]X
1121 command are not interpreted by
1122 .IR \%troff ,
1123 so vertical space for the graphic is not automatically added,
1124 and the
1125 .I width
1126 and
1127 .I height
1128 arguments are not allowed to have attached scaling indicators.
1129 .
1130 .
1131 .IP
1132 If the PostScript file complies with the Adobe Document Structuring
1133 Conventions and contains a
1134 .B %%Bounding\%Box
1135 comment,
1136 then the bounding box can be automatically extracted from within
1137 .I groff
1138 input by using the
1139 .B psbb
1140 request.
1141 .
1142 .
1143 .IP
1144 See
1145 .MR groff_tmac 5
1146 for a description of the
1147 .B PSPIC
1148 macro which provides a convenient high-level interface for inclusion of
1149 PostScript graphics.
1150 .
1151 .
1152 .TP
1153 .B \[rs]X\[aq]ps: invis\[aq]
1154 .TQ
1155 .B \[rs]X\[aq]ps: endinvis\[aq]
1156 No output is generated for text and drawing commands
1157 that are bracketed with these
1158 .B \[rs]X
1159 commands.
1160 .
1161 These commands are intended for use when output from
1162 .I \%troff
1163 is previewed before being processed with
1164 .IR grops ;
1165 if the previewer is unable to display certain characters
1166 or other constructs,
1167 then other substitute characters or constructs can be used for
1168 previewing by bracketing them with these
1169 .B \[rs]X
1170 commands.
1171 .
1172 .
1173 .RS
1174 .P
1175 For example,
1176 .I \%gxditview
1177 is not able to display a proper
1178 .B \[rs][em]
1179 character because the standard X11 fonts do not provide it;
1180 this problem can be overcome by executing the following
1181 request
1182 .
1183 .
1184 .IP
1185 .EX
1186 \&.char \[rs][em] \[rs]X\[aq]ps: invis\[aq]\[rs]
1187 \[rs]Z\[aq]\[rs]v\[aq]-.25m\[aq]\[rs]h\[aq].05m\[aq]\c
1188 \[rs]D\[aq]l .9m 0\[aq]\[rs]h\[aq].05m\[aq]\[aq]\[rs]
1189 \[rs]X\[aq]ps: endinvis\[aq]\[rs][em]
1190 .EE
1191 .
1192 .
1193 .P
1194 In this case,
1195 .I \%gxditview
1196 is unable to display the
1197 .B \[rs][em]
1198 character and draws the line,
1199 whereas
1200 .I grops
1201 prints the
1202 .B \[rs][em]
1203 character
1204 and ignores the line
1205 (this code is already in file
1206 .IR Xps.tmac ,
1207 which is loaded if a document intended for
1208 .I grops
1209 is previewed with
1210 .IR \%gxditview ).
1211 .RE
1212 .
1213 .
1214 .P
1215 If a PostScript procedure
1216 .B BPhook
1217 has been defined via a
1218 .RB \[lq] "ps: def" \[rq]
1219 or
1220 .RB \[lq] "ps: mdef" \[rq]
1221 device control command,
1222 it is executed at the beginning of every page
1223 (before anything is drawn or written by
1224 .IR groff ).
1225 .
1226 For example,
1227 to underlay the page contents with the word \[lq]DRAFT\[rq] in light
1228 gray,
1229 you might use
1230 .
1231 .
1232 .RS
1233 .P
1234 .EX
1235 \&.de XX
1236 ps: def
1237 /BPhook
1238 { gsave .9 setgray clippath pathbbox exch 2 copy
1239 .5 mul exch .5 mul translate atan rotate pop pop
1240 /NewCenturySchlbk-Roman findfont 200 scalefont setfont
1241 (DRAFT) dup stringwidth pop \-.5 mul \-70 moveto show
1242 grestore }
1243 def
1244 \&..
1245 \&.devicem XX
1246 .EE
1247 .RE
1248 .
1249 .
1250 .P
1251 Or,
1252 to cause lines and polygons to be drawn with square linecaps and mitered
1253 linejoins instead of the round linecaps and linejoins normally used by
1254 .IR grops ,
1255 use
1256 .
1257 .RS
1258 .EX
1259 \&.de XX
1260 ps: def
1261 /BPhook { 2 setlinecap 0 setlinejoin } def
1262 \&..
1263 \&.devicem XX
1264 .EE
1265 .RE
1266 .
1267 (square linecaps,
1268 as opposed to butt linecaps
1269 .RB (\[lq] "0 setlinecap" \[rq]),
1270 give true corners in boxed tables even though the lines are drawn
1271 unconnected).
1272 .
1273 .
1274 .\" ====================================================================
1275 .SS "Encapsulated PostScript"
1276 .\" ====================================================================
1277 .
1278 .I grops
1279 itself doesn't emit bounding box information.
1280 .
1281 The following script,
1282 .IR groff2eps ,
1283 produces an EPS file.
1284 .
1285 .
1286 .RS
1287 .P
1288 .EX
1289 #! /bin/sh
1290 groff \-P\-b16 "$1" > "$1".ps
1291 gs \-dNOPAUSE \-sDEVICE=bbox \-\- "$1".ps 2> "$1".bbox
1292 sed \-e "/\[ha]%%Orientation/r $1.bbox" \[rs]
1293 \-e "/\[ha]%!PS\-Adobe\-3.0/s/$/ EPSF\-3.0/" "$1".ps > "$1".eps
1294 rm "$1".ps "$1".bbox
1295 .EE
1296 .RE
1297 .
1298 .
1299 .P
1300 You can then use
1301 .RB \[lq] "groff2eps foo" \[rq]
1302 to convert file
1303 .I foo
1304 to
1305 .IR foo.eps .
1306 .
1307 .
1308 .\" ====================================================================
1309 .SS "TrueType and other font formats"
1310 .\" ====================================================================
1311 .
1312 TrueType fonts can be used with
1313 .I grops
1314 if converted first to Type\~42 format,
1315 a PostScript wrapper equivalent to the PFA format described in
1316 .MR pfbtops 1 .
1317 .
1318 Several methods exist to generate a Type\~42 wrapper;
1319 some of them involve the use of a PostScript interpreter such as
1320 Ghostscript\[em]see
1321 .MR gs 1 .
1322 .
1323 .
1324 .P
1325 One approach is to use
1326 .UR https://fontforge.org/
1327 FontForge
1328 .UE ,
1329 a font editor that can convert most outline font formats.
1330 .
1331 Here's an example of using the Roboto Slab Serif font with
1332 .IR groff .
1333 .
1334 Several variables are used so that you can more easily adapt it into
1335 your own script.
1336 .
1337 .
1338 .RS 4
1339 .P
1340 .EX
1341 MAP=/usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/devps/generate/text.map
1342 TTF=/usr/share/fonts/truetype/roboto/slab/RobotoSlab\-Regular.ttf
1343 BASE=$(basename \[dq]$TTF\[dq])
1344 INT=${BASE%.ttf}
1345 PFA=$INT.pfa
1346 AFM=$INT.afm
1347 GFN=RSR
1348 DIR=$HOME/.local/groff/font
1349 mkdir \-p \[dq]$DIR\[dq]/devps
1350 fontforge \-lang=ff \-c \[dq]Open(\[rs]\[dq]$TTF\[rs]\[dq]);\[rs]
1351 \tGenerate(\[rs]\[dq]$DIR/devps/$PFA\[rs]\[dq]);\[dq]
1352 afmtodit \[dq]$DIR/devps/$AFM\[dq] \[dq]$MAP\[dq] \
1353 \[dq]$DIR/devps/$GFN\[dq]
1354 printf \[dq]$BASE\[rs]t$PFA\[rs]n\[dq] >> \[dq]$DIR/devps/download\[dq]
1355 .EE
1356 .RE
1357 .
1358 .
1359 .P
1360 .I fontforge
1361 and
1362 .I afmtodit
1363 may generate warnings depending on the attributes of the font.
1364 .
1365 The test procedure is simple.
1366 .
1367 .
1368 .RS 4
1369 .P
1370 .EX
1371 printf \[dq].ft RSR\[rs]nHello, world!\[rs]n\[dq] | groff \-F \
1372 \[dq]$DIR\[dq] > hello.ps
1373 .EE
1374 .RE
1375 .
1376 .
1377 .P
1378 Once you're satisfied that the font works,
1379 you may want to generate any available related styles
1380 (for instance,
1381 Roboto Slab
1382 also has \[lq]Bold\[rq],
1383 \[lq]Light\[rq],
1384 and
1385 \[lq]Thin\[rq]
1386 styles)
1387 and set up
1388 .I GROFF_FONT_PATH
1389 in your environment to include the directory you keep the generated
1390 fonts in so that you don't have to use the
1391 .B \-F
1392 option.
1393 .
1394 .
1395 .\" ====================================================================
1396 .SH "Font installation"
1397 .\" ====================================================================
1398 .
1399 The following is a step-by-step font installation guide for
1400 .I grops.
1401 .
1402 .
1403 .IP \[bu] 2n
1404 Convert your font to something
1405 .I groff
1406 understands.
1407 .
1408 This is a PostScript Type\~1 font in PFA format or a PostScript
1409 Type\~42 font,
1410 together with an AFM file.
1411 .
1412 A PFA file begins as follows.
1413 .
1414 .RS
1415 .RS \" two RS calls to get inboard of IP indentation
1416 .EX
1417 %!PS\-AdobeFont\-1.0:
1418 .EE
1419 .RE
1420 .
1421 A PFB file contains this string as well,
1422 preceded by some non-printing bytes.
1423 .
1424 If your font is in PFB format,
1425 use
1426 .IR groff 's
1427 .MR pfbtops 1
1428 program to convert it to PFA.
1429 .
1430 For TrueType and other font formats,
1431 we recommend
1432 .IR fontforge ,
1433 which can convert most outline font formats.
1434 .
1435 A Type\~42 font file begins as follows.
1436 .
1437 .RS
1438 .EX
1439 %!PS\-TrueTypeFont
1440 .EE
1441 .RE
1442 .
1443 This is a wrapper format for TrueType fonts.
1444 .
1445 Old PostScript printers might not support them
1446 (that is,
1447 they might not have a built-in TrueType font interpreter).
1448 .
1449 In the following steps,
1450 we will consider the use of CTAN's
1451 .UR https://\:ctan.org/\:tex\-archive/\:fonts/\:brushscr
1452 BrushScriptX-Italic
1453 .UE
1454 font in PFA format.
1455 .RE \" now restore left margin
1456 .
1457 .
1458 .IP \[bu]
1459 Convert the AFM file to a
1460 .I groff
1461 font description file with the
1462 .MR afmtodit 1
1463 program.
1464 .
1465 For instance,
1466 .
1467 .RS
1468 .RS \" two RS calls to get inboard of IP indentation
1469 .EX
1470 $ \c
1471 .B afmtodit BrushScriptX\-Italic.afm text.map BSI
1472 .EE
1473 .RE
1474 .
1475 converts the Adobe Font Metric file
1476 .I BrushScriptX\-Italic.afm
1477 to the
1478 .I groff
1479 font description file
1480 .IR BSI .
1481 .RE \" now restore left margin
1482 .
1483 .
1484 .IP
1485 If you have a font family which provides regular upright (roman),
1486 bold,
1487 italic,
1488 and
1489 bold-italic styles
1490 (where \[lq]italic\[rq] may be \[lq]oblique\[rq] or \[lq]slanted\[rq]),
1491 we recommend using the letters
1492 .BR R ,
1493 .BR B ,
1494 .BR I ,
1495 and
1496 .BR BI ,
1497 respectively,
1498 as suffixes to the
1499 .I groff
1500 font family name to enable
1501 .IR groff 's
1502 font family and style selection features.
1503 .
1504 An example is
1505 .IR groff 's
1506 built-in support for Times:
1507 the font family
1508 name is abbreviated as
1509 .BR T ,
1510 and the
1511 .I groff
1512 font names are therefore
1513 .BR TR ,
1514 .BR TB ,
1515 .BR TI ,
1516 and
1517 .BR TBI .
1518 .
1519 In our example,
1520 however,
1521 the BrushScriptX font is available in a single style only,
1522 italic.
1523 .
1524 .
1525 .IP \[bu]
1526 Install the
1527 .I groff
1528 font description file(s) in a
1529 .I devps
1530 subdirectory in the search path that
1531 .I groff
1532 uses for device and font file descriptions.
1533 .
1534 See the
1535 .I GROFF_FONT_PATH
1536 entry in section \[lq]Environment\[rq] of
1537 .MR \%troff 1
1538 for the current value of the font search path.
1539 .
1540 While
1541 .I groff
1542 doesn't directly use AFM files,
1543 it is a good idea to store them alongside its font description files.
1544 .
1545 .
1546 .IP \[bu]
1547 Register fonts in the
1548 .I devps/download
1549 file so they can be located for embedding in PostScript files
1550 .I grops
1551 generates.
1552 .
1553 Only the first
1554 .I download
1555 file encountered in the font search path is read.
1556 .
1557 If in doubt,
1558 copy the default
1559 .I download
1560 file
1561 (see section \[lq]Files\[rq] below)
1562 to the first directory in the font search path and add your fonts there.
1563 .
1564 The PostScript font name used by
1565 .I grops
1566 is stored in the
1567 .B internalname
1568 field in the
1569 .I groff
1570 font description file.
1571 .
1572 (This name does not necessarily resemble the font's file name.)
1573 .
1574 We add the following line to
1575 .IR download .
1576 .
1577 .RS
1578 .RS \" two RS calls to get inboard of IP indentation
1579 .EX
1580 BrushScriptX\-Italic\[->]BrushScriptX\-Italic.pfa
1581 .EE
1582 .RE \" but only one to get back to it
1583 .
1584 A tab character,
1585 depicted as \[->],
1586 separates the fields.
1587 .RE \" now restore left margin
1588 .
1589 .
1590 .IP \[bu]
1591 Test the selection and embedding of the new font.
1592 .
1593 .RS
1594 .RS \" two RS calls to get inboard of IP indentation
1595 .EX
1596 printf "\[rs]\[rs]f[BSI]Hello, world!\[rs]n" \
1597 | groff \-T ps \-P \-e >hello.ps
1598 see hello.pdf
1599 .EE
1600 .RE
1601 .RE \" now restore left margin
1602 .
1603 .
1604 .\" ====================================================================
1605 .SH "Old fonts"
1606 .\" ====================================================================
1607 .
1608 .I groff
1609 versions 1.19.2 and earlier contained descriptions of a slightly
1610 different set of the base 35 PostScript level 2 fonts defined by Adobe.
1611 .
1612 The older set has 229 glyphs and a larger set of kerning pairs;
1613 the newer one has 314 glyphs and includes the Euro glyph.
1614 .
1615 For backwards compatibility,
1616 these old font descriptions are also installed in the
1617 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%oldfont/\:\%devps
1618 directory.
1619 .
1620 .
1621 .P
1622 To use them,
1623 make sure that
1624 .I grops
1625 finds the fonts before the default system fonts
1626 (with the same names):
1627 either give
1628 .I grops
1629 the
1630 .B \-F
1631 command-line option,
1632 .
1633 .RS
1634 .EX
1635 $ \c
1636 .B groff \-Tps \-P\-F \-P/usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%oldfont \c
1637 \&.\|.\|.
1638 .EE
1639 .RE
1640 .
1641 or add the directory to
1642 .IR groff 's
1643 font and device description search path environment variable,
1644 .
1645 .RS
1646 .EX
1647 $ \c
1648 .B GROFF_FONT_PATH=\:/usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%oldfont \[rs]
1649 .RS
1650 .B groff \-Tps \c
1651 \&.\|.\|.
1652 .RE
1653 .EE
1654 .RE
1655 .
1656 when the command runs.
1657 .
1658 .
1659 .br
1660 .ne 3v
1661 .\" ====================================================================
1662 .SH Environment
1663 .\" ====================================================================
1664 .
1665 .TP
1666 .I GROFF_FONT_PATH
1667 A list of directories in which to seek the selected output device's
1668 directory of device and font description files.
1669 .
1670 See
1671 .MR \%troff 1
1672 and
1673 .MR groff_font 5 .
1674 .
1675 .
1676 .TP
1677 .I GROPS_PROLOGUE
1678 If this is set to
1679 .IR foo ,
1680 then
1681 .I grops
1682 uses the file
1683 .I foo
1684 (in the font path) instead of the default prologue file
1685 .IR prologue .
1686 .
1687 The option
1688 .B \-P
1689 overrides this environment variable.
1690 .
1691 .
1692 .TP
1693 .I SOURCE_DATE_EPOCH
1694 A timestamp
1695 (expressed as seconds since the Unix epoch)
1696 to use as the output creation timestamp in place of the current time.
1697 .
1698 The time is converted to human-readable form using
1699 .MR gmtime 3
1700 and
1701 .MR asctime 3 ,
1702 and recorded in a PostScript comment.
1703 .
1704 .
1705 .TP
1706 .I TZ
1707 The time zone to use when converting the current time to human-readable form;
1708 see
1709 .MR tzset 3 .
1710 If
1711 .I SOURCE_DATE_EPOCH
1712 is used, it is always converted to human-readable form using UTC.
1713 .
1714 .
1715 .\" ====================================================================
1716 .SH Files
1717 .\" ====================================================================
1718 .
1719 .TP
1720 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:DESC
1721 describes the
1722 .B ps
1723 output device.
1724 .
1725 .
1726 .TP
1727 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/ F
1728 describes the font known
1729 .RI as\~ F
1730 on device
1731 .BR ps .
1732 .
1733 .
1734 .TP
1735 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%download
1736 lists fonts available for embedding within the PostScript document
1737 (or download to the device).
1738 .
1739 .
1740 .TP
1741 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%prologue
1742 is the default PostScript prologue prefixed to every output file.
1743 .
1744 .
1745 .TP
1746 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:text.enc
1747 describes the encoding scheme used by most PostScript Type\~1 fonts;
1748 the
1749 .B \%encoding
1750 directive of
1751 font description files for the
1752 .B ps
1753 device refers to it.
1754 .
1755 .
1756 .TP
1757 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:ps.tmac
1758 defines macros for use with the
1759 .B ps
1760 output device.
1761 .
1762 It is automatically loaded by
1763 .I troffrc
1764 when the
1765 .B ps
1766 output device is selected.
1767 .
1768 .
1769 .TP
1770 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:pspic.tmac
1771 defines the
1772 .B PSPIC
1773 macro for embedding images in a document;
1774 see
1775 .MR groff_tmac 5 .
1776 .
1777 It is automatically loaded by
1778 .I troffrc.
1779 .
1780 .
1781 .TP
1782 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/psold.tmac
1783 provides replacement glyphs for text fonts that lack complete coverage
1784 of the ISO Latin-1 character set;
1785 using it,
1786 .I groff
1787 can produce glyphs like eth (\[Sd]) and thorn (\[Tp]) that older
1788 PostScript printers do not natively support.
1789 .
1790 .
1791 .P
1792 .I grops
1793 creates temporary files using the template
1794 .RI \[lq] grops XXXXXX\[rq];
1795 see
1796 .MR groff 1
1797 for details on their storage location.
1798 .
1799 .
1800 .\" ====================================================================
1801 .SH "See also"
1802 .\" ====================================================================
1803 .
1804 .UR http://\:partners\:.adobe\:.com/\:public/\:developer/\:en/\:ps/\
1805 \:5001\:.DSC_Spec\:.pdf
1806 PostScript Language Document Structuring Conventions Specification
1807 .UE
1808 .
1809 .
1810 .P
1811 .MR afmtodit 1 ,
1812 .MR groff 1 ,
1813 .MR \%troff 1 ,
1814 .MR pfbtops 1 ,
1815 .MR groff_char 7 ,
1816 .MR groff_font 5 ,
1817 .MR groff_out 5 ,
1818 .MR groff_tmac 5
1819 .
1820 .
1821 .\" Clean up.
1822 .rm FT
1823 .
1824 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1825 .cp \n[*groff_grops_1_man_C]
1826 .do rr *groff_grops_1_man_C
1827 .
1828 .
1829 .\" Local Variables:
1830 .\" fill-column: 72
1831 .\" mode: nroff
1832 .\" End:
1833 .\" vim: set filetype=groff textwidth=72: