* Makefile.in (oldfontdir): New variable.
[s-roff.git] / src / devices / grops / grops.man
blobb8d776f966b1611ec6fda3b58abba8fdcba904ba
1 .ig
2 Copyright (C) 1989-2000, 2001, 2002, 2003, 2004, 2005, 2006
3   Free Software Foundation, Inc.
5 Permission is granted to make and distribute verbatim copies of
6 this manual provided the copyright notice and this permission notice
7 are preserved on all copies.
9 Permission is granted to copy and distribute modified versions of this
10 manual under the conditions for verbatim copying, provided that the
11 entire resulting derived work is distributed under the terms of a
12 permission notice identical to this one.
14 Permission is granted to copy and distribute translations of this
15 manual into another language, under the above conditions for modified
16 versions, except that this permission notice may be included in
17 translations approved by the Free Software Foundation instead of in
18 the original English.
21 .do nr grops_C \n[.C]
22 .cp 0
24 .mso www.tmac
27 .\" Like TP, but if specified indent is more than half
28 .\" the current line-length - indent, use the default indent.
29 .de Tp
30 .  ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
31 .  el .TP "\\$1"
34 .de TQ
35 .  br
36 .  ns
37 .  TP \\$1
40 .de FT
41 .  if '\\*(.T'ps' .ft \\$1
45 .TH GROPS @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
48 .SH NAME
49 grops \- PostScript driver for groff
52 .SH SYNOPSIS
53 .nr a \n(.j
54 .ad l
55 .nr i \n(.i
56 .in +\w'\fBgrops 'u
57 .ti \niu
58 .B grops
60 .de OP
61 .  ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\%\\$2" "\ ]"
62 .  el .RB "[\ " "\\$1" "\ ]"
65 .OP \-glmv
66 .OP \-b n
67 .OP \-c n
68 .OP \-F dir
69 .OP \-I dir
70 .OP \-p papersize
71 .OP \-P prologue
72 .OP \-w n
73 .RI "[\ " files\|.\|.\|. "\ ]"
74 .br
75 .ad \na
77 .PP
78 It is possible to have whitespace between a command line option and its
79 parameter.
82 .SH DESCRIPTION
83 .B grops
84 translates the output of GNU
85 .B troff
86 to PostScript.
88 Normally
89 .B grops
90 should be invoked by using the groff command
91 with a
92 .B \-Tps
93 option.
95 .if '@DEVICE@'ps' (Actually, this is the default for groff.)
97 If no files are given,
98 .B grops
99 reads the standard input.
101 A filename of
102 .B \-
103 also causes
104 .B grops
105 to read the standard input.
107 PostScript output is written to the standard output.
109 When
110 .B grops
111 is run by
112 .B groff
113 options can be passed to
114 .B grops
115 using
116 .BR groff 's
117 .B \-P
118 option.
121 Note that
122 .B grops
123 doesn't produce a valid document structure (conforming to the Document
124 Structuring Convention) if called with multiple file arguments.
126 To print such concatenated output it is necessary to deactivate DSC
127 handling in the printing program or previewer.
129 See section
130 .B FONT INSTALLATION
131 below for a guide how to install fonts for
132 .BR grops .
135 .SH OPTIONS
137 .BI \-b n
138 Provide workarounds for older printers, broken spoolers, and previewers.
140 Normally
141 .B grops
142 produces output at PostScript LanguageLevel\~2 that conforms to the
143 Document Structuring Conventions version 3.0.
145 Some older printers, spoolers, and previewers can't handle such output.
147 The value of\~\c
148 .I n
149 controls what
150 .B grops
151 does to make its output acceptable to such programs.
153 A value of\~0 causes grops not to employ any workarounds.
156 Add\~1 if no
157 .B %%Begin\%Document\%Setup
159 .B %%End\%Document\%Setup
160 comments should be generated;
161 this is needed for early versions of TranScript that get confused by
162 anything between the
163 .B %%End\%Prolog
164 comment and the first
165 .B %%Page
166 comment.
169 Add\~2 if lines in included files beginning with
170 .B %!\&
171 should be stripped out; this is needed for Sun's pageview previewer.
174 Add\~4 if
175 .BR %%Page ,
176 .BR %%Trailer
178 .B %%End\%Prolog
179 comments should be
180 stripped out of included files; this is needed for spoolers that
181 don't understand the
182 .B %%Begin\%Document
184 .B %%End\%Document
185 comments.
188 Add\~8 if the first line of the PostScript output should be
189 .B %!PS-Adobe-2.0
190 rather than
191 .BR %!PS-Adobe-3.0 ;
192 this is needed when using Sun's Newsprint with a printer that requires
193 page reversal.
196 Add\~16 if no media size information should be included in the document
197 (this is, neither use
198 .B %%Document\%Media
199 nor the
200 .B setpagedevice
201 PostScript command).
203 This was the behaviour of groff version 1.18.1 and earlier; it is needed
204 for older printers which don't understand PostScript LanguageLevel\~2.
206 It is also necessary if the output is further processed to get an
207 encapsulated PS (EPS) file \[en] see below.
210 The default value can be specified by a
214 .BI broken\  n
217 command in the DESC file.
219 Otherwise the default value is\~0.
223 .BI \-c n
224 Print
225 .I n
226 copies of each page.
229 .BI \-F dir
230 Prepend directory
231 .IB dir /dev name
232 to the search path for prologue, font, and device description files;
233 .I name
234 is the name of the device, usually
235 .BR ps .
238 .BI \-g
239 Guess the page length.
241 This generates PostScript code that guesses the page length.
243 The guess is correct only if the imageable area is vertically
244 centered on the page.
246 This option allows you to generate documents that can be printed
247 both on letter (8.5\[mu]11) paper and on A4 paper without change.
250 .BI \-I dir
251 This option may be used to specify a directory to search for
252 files on the command line and files named in
253 .B \[rs]X'ps: import'
255 .B \[rs]X'ps: file'
256 escapes.
258 The current directory is always searched first.
260 This option may be specified more than once;
261 the directories are searched in the order specified.
263 No directory search is performed for files specified using an absolute path.
266 .B \-l
267 Print the document in landscape format.
270 .B \-m
271 Turn manual feed on for the document.
274 .BI \-p paper-size
275 Set physical dimension of output medium.
277 This overrides the
278 .BR papersize ,
279 .BR paperlength ,
281 .B paperwidth
282 commands in the
283 .B DESC
284 file; it accepts the same arguments as the
285 .B papersize
286 command.
289 .B groff_font (@MAN5EXT@)
290 for details.
293 .BI \-P prologue-file
294 Use the file
295 .I prologue-file
296 (in the font path) as the prologue instead of the default prologue file
297 .BR prologue .
299 This option overrides the environment variable
300 .SM GROPS_PROLOGUE.
303 .BI \-w n
304 Lines should be drawn using a thickness of
305 .IR n \~\c
306 thousandths of an em.
308 If this option is not given, the line thickness defaults to 0.04\~em.
311 .B \-v
312 Print the version number.
315 .SH USAGE
316 The input to
317 .B grops
318 must be in the format output by
319 .BR @g@troff (@MAN1EXT@).
321 This is described in
322 .BR groff_out (@MAN5EXT@).
325 In addition, the device and font description files for the device used
326 must meet certain requirements:
328 The resolution must be an integer multiple of\~72 times the
329 .BR sizescale .
332 .B ps
333 device uses a resolution of 72000 and a sizescale of 1000.
336 The device description file must contain a valid paper size; see
337 .BR groff_font (@MAN5EXT@)
338 for more information.
341 Each font description file must contain a command
343 .BI internalname\  psname
345 which says that the PostScript name of the font is
346 .IR psname .
348 It may also contain a command
350 .BI encoding\  enc_file
352 which says that
353 the PostScript font should be reencoded using the encoding described in
354 .IR enc_file ;
355 this file should consist of a sequence of lines of the form:
358 pschar code
360 where
361 .I pschar
362 is the PostScript name of the character,
364 .I code
365 is its position in the encoding expressed as a decimal integer; valid
366 values are in the range 0 to\~255.
368 Lines starting with
369 .B #
370 and blank lines are ignored.
372 The code for each character given in the font file must correspond
373 to the code for the character in encoding file, or to the code in the default
374 encoding for the font if the PostScript font is not to be reencoded.
376 This code can be used with the
377 .B \[rs]N
378 escape sequence in
379 .B troff
380 to select the character,
381 even if the character does not have a groff name.
383 Every character in the font file must exist in the PostScript font, and
384 the widths given in the font file must match the widths used
385 in the PostScript font.
387 .B grops
388 assumes that a character with a groff name of
389 .B space
390 is blank (makes no marks on the page);
391 it can make use of such a character to generate more efficient and
392 compact PostScript output.
395 Note that
396 .B grops
397 is able to display all glyphs in a PostScript font, not only 256.
398 .I enc_file
399 (or the default encoding if no encoding file specified) just defines the
400 order of glyphs for the first 256 characters; all other glyphs are
401 accessed with additional encoding vectors which
402 .B grops
403 produces on the fly.
406 .B grops
407 can automatically include the downloadable fonts necessary
408 to print the document.
410 Such fonts must be in PFA format.
413 .BR \%pfbtops (@MAN1EXT@)
414 to convert a Type\~1 font in PFB format.
416 Any downloadable fonts which should, when required, be included by
417 .B grops
418 must be listed in the file
419 .BR @FONTDIR@/devps/download ;
420 this should consist of lines of the form
424 font filename
427 where
428 .I font
429 is the PostScript name of the font,
431 .I filename
432 is the name of the file containing the font;
433 lines beginning with
434 .B #
435 and blank lines are ignored;
436 fields may be separated by tabs or spaces;
437 .I filename
438 is searched for using the same mechanism that is used
439 for groff font metric files.
442 .B download
443 file itself is also searched for using this mechanism;
444 currently, only the first found file in the font path is used.
447 If the file containing a downloadable font or imported document
448 conforms to the Adobe Document Structuring Conventions,
449 then
450 .B grops
451 interprets any comments in the files sufficiently to ensure that its
452 own output is conforming.
454 It also supplies any needed font resources that are listed in the
455 .B download
456 file
457 as well as any needed file resources.
459 It is also able to handle inter-resource dependencies.
461 For example, suppose that you have a downloadable font called Garamond,
462 and also a downloadable font called Garamond-Outline
463 which depends on Garamond
464 (typically it would be defined to copy Garamond's font dictionary,
465 and change the PaintType),
466 then it is necessary for Garamond to appear before Garamond-Outline
467 in the PostScript document.
469 .B grops
470 handles this automatically
471 provided that the downloadable font file for Garamond-Outline
472 indicates its dependence on Garamond by means of
473 the Document Structuring Conventions,
474 for example by beginning with the following lines
478 %!PS-Adobe-3.0 Resource-Font
481 %%DocumentNeededResources: font Garamond
484 %%EndComments
487 %%IncludeResource: font Garamond
490 In this case both Garamond and Garamond-Outline would need to be listed
491 in the
492 .B download
493 file.
495 A downloadable font should not include its own name in a
496 .B %%Document\%Supplied\%Resources
497 comment.
500 .B grops
501 does not interpret
502 .B %%Document\%Fonts
503 comments.
506 .BR %%Document\%Needed\%Resources ,
507 .BR %%Document\%Supplied\%Resources ,
508 .BR %%Include\%Resource ,
509 .BR %%Begin\%Resource ,
511 .BR %%End\%Resource
512 comments
513 (or possibly the old
514 .BR %%Document\%Needed\%Fonts ,
515 .BR %%Document\%Supplied\%Fonts ,
516 .BR %%Include\%Font ,
517 .BR %%Begin\%Font ,
519 .BR %%End\%Font
520 comments)
521 should be used.
524 In the default setup
525 there are styles called
526 .BR R ,
527 .BR I ,
528 .BR B ,
530 .B BI
531 mounted at font positions 1 to\~4.
533 The fonts are grouped into families
534 .BR A ,
535 .BR BM ,
536 .BR C ,
537 .BR H ,
538 .BR HN ,
539 .BR N ,
540 .BR P ,
541 and\~\c
542 .B T
543 having members in each of these styles:
547 .B AR
548 .FT AR
549 AvantGarde-Book
553 .B AI
554 .FT AI
555 AvantGarde-BookOblique
559 .B AB
560 .FT AB
561 AvantGarde-Demi
565 .B ABI
566 .FT ABI
567 AvantGarde-DemiOblique
571 .B BMR
572 .FT BMR
573 Bookman-Light
577 .B BMI
578 .FT BMI
579 Bookman-LightItalic
583 .B BMB
584 .FT BMB
585 Bookman-Demi
589 .B BMBI
590 .FT BMBI
591 Bookman-DemiItalic
595 .B CR
596 .FT CR
597 Courier
601 .B CI
602 .FT CI
603 Courier-Oblique
607 .B CB
608 .FT CB
609 Courier-Bold
613 .B CBI
614 .FT CBI
615 Courier-BoldOblique
619 .B HR
620 .FT HR
621 Helvetica
625 .B HI
626 .FT HI
627 Helvetica-Oblique
631 .B HB
632 .FT HB
633 Helvetica-Bold
637 .B HBI
638 .FT HBI
639 Helvetica-BoldOblique
643 .B HNR
644 .FT HNR
645 Helvetica-Narrow
649 .B HNI
650 .FT HNI
651 Helvetica-Narrow-Oblique
655 .B HNB
656 .FT HNB
657 Helvetica-Narrow-Bold
661 .B HNBI
662 .FT HNBI
663 Helvetica-Narrow-BoldOblique
667 .B NR
668 .FT NR
669 NewCenturySchlbk-Roman
673 .B NI
674 .FT NI
675 NewCenturySchlbk-Italic
679 .B NB
680 .FT NB
681 NewCenturySchlbk-Bold
685 .B NBI
686 .FT NBI
687 NewCenturySchlbk-BoldItalic
691 .B PR
692 .FT PR
693 Palatino-Roman
697 .B PI
698 .FT PI
699 Palatino-Italic
703 .B PB
704 .FT PB
705 Palatino-Bold
709 .B PBI
710 .FT PBI
711 Palatino-BoldItalic
715 .B TR
716 .FT TR
717 Times-Roman
721 .B TI
722 .FT TI
723 Times-Italic
727 .B TB
728 .FT TB
729 Times-Bold
733 .B TBI
734 .FT TBI
735 Times-BoldItalic
740 There is also the following font which is not a member of a family:
744 .B ZCMI
745 .FT ZCMI
746 ZapfChancery-MediumItalic
751 There are also some special fonts called
752 .B S
753 for the PS Symbol font, and
754 .BR SS ,
755 containing slanted lowercase Greek letters taken from PS Symbol.
757 Zapf Dingbats is available as
758 .BR ZD ,
759 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
760 direction) is available as
761 .BR ZDR ;
762 most characters in these fonts are unnamed and must be accessed using
763 .BR \[rs]N .
766 The default color for
767 .B \[rs]m
769 .B \[rs]M
770 is black; for colors defined in the `rgb' color space
771 .B setrgbcolor
772 is used, for `cmy' and `cmyk'
773 .BR setcmykcolor ,
774 and for `gray'
775 .BR setgray .
777 Note that
778 .B setcmykcolor
779 is a PostScript LanguageLevel\~2 command and thus not available on some
780 older printers.
783 .B grops
784 understands various X\~commands produced using the
785 .B \[rs]X
786 escape sequence;
787 .B grops
788 only interprets commands that begin with a
789 .B ps:
790 tag.
793 .BI \[rs]X'ps:\ exec\  code '
794 This executes the arbitrary PostScript commands in
795 .IR code .
797 The PostScript currentpoint is set to the position of the
798 .B \[rs]X
799 command before executing
800 .IR code .
802 The origin is at the top left corner of the page,
803 and y\~coordinates increase down the page.
805 A procedure\~\c
806 .B u
807 is defined that converts groff units
808 to the coordinate system in effect (provided the user doesn't change the
809 scale).
811 For example,
816 \&.nr x 1i
819 \[rs]X'ps: exec \[rs]nx u 0 rlineto stroke'
824 draws a horizontal line one inch long.
826 .I code
827 may make changes to the graphics state,
828 but any changes persist only to the end of the page.
830 A dictionary containing the definitions specified by the
831 .B def
833 .B mdef
834 is on top of the dictionary stack.
836 If your code adds definitions to this dictionary,
837 you should allocate space for them using
838 .BI \[rs]X'ps\ mdef \ n '\fR.
840 Any definitions persist only until the end of the page.
842 If you use the
843 .B \[rs]Y
844 escape sequence with an argument that names a macro,
845 .I code
846 can extend over multiple lines.
848 For example,
853 .ft B
854 \&.nr x 1i
855 \&.de y
856 \&ps: exec
857 \&\[rs]nx u 0 rlineto
858 \&stroke
859 \&..
860 \&\[rs]Yy
861 .ft R
865 is another way to draw a horizontal line one inch long.
867 Note the single backslash before `nx' \[en] the only reason to use a number
868 register while defining the macro `y' is to convert a user-specified
869 dimension `1i' to internal groff units which are in turn converted to PS
870 units with the
871 .B u
872 procedure.
875 .B grops
876 wraps user-specified PostScript code into a dictionary, nothing more.
878 In particular, it doesn't start and end the inserted code with
879 .B save
881 .BR restore ,
882 respectively.
884 This must be supplied by the user, if necessary.
889 .BI \[rs]X'ps:\ file\  name '
890 This is the same as the
891 .B exec
892 command except that the PostScript code is read from file
893 .IR name .
896 .BI \[rs]X'ps:\ def\  code '
897 Place a PostScript definition contained in
898 .I code
899 in the prologue.
901 There should be at most one definition per
902 .B \[rs]X
903 command.
905 Long definitions can be split over several
906 .B \[rs]X
907 commands;
908 all the
909 .I code
910 arguments are simply joined together separated by newlines.
912 The definitions are placed in a dictionary which is automatically
913 pushed on the dictionary stack when an
914 .B exec
915 command is executed.
917 If you use the
918 .B \[rs]Y
919 escape sequence with an argument that names a macro,
920 .I code
921 can extend over multiple lines.
924 .BI \[rs]X'ps:\ mdef\  n\ code  '
925 Like
926 .BR def ,
927 except that
928 .I code
929 may contain up to
930 .IR n \~\c
931 definitions.
933 .B grops
934 needs to know how many definitions
935 .I code
936 contains
937 so that it can create an appropriately sized PostScript dictionary
938 to contain them.
941 .BI \[rs]X'ps:\ import\  file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
942 Import a PostScript graphic from
943 .IR file .
945 The arguments
946 .IR llx ,
947 .IR lly ,
948 .IR urx ,
950 .I ury
951 give the bounding box of the graphic in the default PostScript
952 coordinate system; they should all be integers;
953 .I llx
955 .I lly
956 are the x and y\~coordinates of the lower left
957 corner of the graphic;
958 .I urx
960 .I ury
961 are the x and y\~coordinates of the upper right corner of the graphic;
962 .I width
964 .I height
965 are integers that give the desired width and height in groff
966 units of the graphic.
969 The graphic is scaled so that it has this width and height
970 and translated so that the lower left corner of the graphic is
971 located at the position associated with
972 .B \[rs]X
973 command.
975 If the height argument is omitted it is scaled uniformly in the
976 x and y\~directions so that it has the specified width.
979 Note that the contents of the
980 .B \[rs]X
981 command are not interpreted by
982 .BR troff ;
983 so vertical space for the graphic is not automatically added,
984 and the
985 .I width
987 .I height
988 arguments are not allowed to have attached scaling indicators.
991 If the PostScript file complies with the Adobe Document Structuring
992 Conventions and contains a
993 .B %%Bounding\%Box
994 comment, then the bounding box can be automatically
995 extracted from within groff by using the
996 .B psbb
997 request.
1001 .BR groff_tmac (@MAN5EXT@)
1002 for a description of the
1003 .B PSPIC
1004 macro which provides a convenient high-level interface for inclusion of
1005 PostScript graphics.
1008 .B \[rs]X'ps:\ invis'
1010 .B \[rs]X'ps:\ endinvis'
1011 No output is generated for text and drawing commands
1012 that are bracketed with these
1013 .B \[rs]X
1014 commands.
1016 These commands are intended for use when output from
1017 .B troff
1018 is previewed before being processed with
1019 .BR grops ;
1020 if the previewer is unable to display certain characters
1021 or other constructs, then other substitute characters or constructs
1022 can be used for previewing by bracketing them with these
1023 .B \[rs]X
1024 commands.
1028 For example,
1029 .B \%gxditview
1030 is not able to display a proper
1031 .B \[rs](em
1032 character because the standard X11 fonts do not provide it;
1033 this problem can be overcome by executing the following
1034 request
1037 .ft B
1039 \&.char \[rs](em \[rs]X'ps: invis'\[rs]
1040 \[rs]Z'\[rs]v'-.25m'\[rs]h'.05m'\[rs]D'l .9m 0'\[rs]h'.05m''\[rs]
1041 \[rs]X'ps: endinvis'\[rs](em
1046 In this case,
1047 .B \%gxditview
1048 is unable to display the
1049 .B \[rs](em
1050 character and draws the line,
1051 whereas
1052 .B grops
1053 prints the
1054 .B \[rs](em
1055 character
1056 and ignores the line (this code is already in file
1057 .B Xps.tmac
1058 which is loaded if a document intended for
1059 .B grops
1060 is previewed with
1061 .BR \%gxditview ).
1065 If a PostScript procedure
1066 .B BPhook
1067 has been defined via a
1068 .RB ` ps:\ def '
1070 .RB ` ps:\ mdef '
1071 device command, it is executed at the beginning
1072 of every page (before anything is drawn or written by groff).
1073 For example, to underlay the page contents with the word
1074 `DRAFT' in light gray, you might use
1078 .ft B
1079 \&.de XX
1080 ps: def
1081 /BPhook
1082 { gsave .9 setgray clippath pathbbox exch 2 copy
1083   .5 mul exch .5 mul translate atan rotate pop pop
1084   /NewCenturySchlbk-Roman findfont 200 scalefont setfont
1085   (DRAFT) dup stringwidth pop \-.5 mul \-70 moveto show
1086   grestore }
1088 \&..
1089 \&.devicem XX
1090 .ft R
1094 Or, to cause lines and polygons to be drawn with square linecaps
1095 and mitered linejoins instead of the round linecaps and linejoins
1096 normally used by
1097 .BR grops ,
1102 .ft B
1103 \&.de XX
1104 ps: def
1105 /BPhook { 2 setlinecap 0 setlinejoin } def
1106 \&..
1107 \&.devicem XX
1108 .ft R
1112 (square linecaps, as opposed to butt linecaps (0 setlinecap),
1113 give true corners in boxed tables even though the lines are
1114 drawn unconnected).
1117 .SS Encapsulated PostScript
1118 .B grops
1119 itself doesn't emit bounding box information.
1121 With the help of Ghostscript the following simple script,
1122 .BR groff2eps ,
1123 produces an encapsulated PS file.
1128 .ft B
1129 #! /bin/sh
1130 groff \-P\-b16 $1 >$1.ps
1131 gs \-dNOPAUSE \-sDEVICE=bbox \-\- $1.ps 2>$1.bbox
1132 cat $1.ps \[rs]
1133 | sed \-e "/\[ha]%%Orientation/r$1.bbox" \[rs]
1134       \-e "/\[ha]%!PS-Adobe-3.0/s/$/ EPSF-3.0/" >$1.eps
1135 rm $1.ps $1.bbox
1136 .ft R
1141 Just say
1145 groff2eps foo
1148 to convert file
1149 .B foo
1151 .BR foo.eps .
1154 .SS TrueType and other font formats
1155 TrueType fonts can be used with
1156 .B grops
1157 if converted first to
1158 .B "Type\~42"
1159 format, a special PostScript wrapper equivalent to the
1160 PFA format mentioned in
1161 .BR \%pfbtops (@MAN1EXT@).
1163 There are several different methods to generate a type42
1164 wrapper and most of them involve the use of a PostScript
1165 interpreter such as Ghostscript \[en] see
1166 .BR gs (1).
1169 Yet, the easiest method involves the use of the application
1170 .BR ttftot42 (1).
1172 This program uses
1173 .BR freetype (3)
1174 (version 1.3.1) to generate type42
1175 font wrappers and well-formed AFM files that can be fed to
1177 .BR \%afmtodit (@MAN1EXT@)
1178 script to create appropriate metric files.
1180 The resulting font wrappers should be added to the
1181 .B download
1182 file.
1183 .B ttftot42
1184 source code can be downloaded from
1185 .URL ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/ \
1186      ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/ .
1189 Another solution for creating type42 wrappers is to use FontForge,
1190 available from
1191 .URL http://\:fontforge.sf.net \
1192      http://\:fontforge.sf.net .
1193 This font editor can convert most outline font formats.
1196 .SH FONT INSTALLATION
1197 This section gives a summary of the above explanations; it can serve
1198 as a step-by-step font installation guide for
1199 .BR grops .
1201 .ds BU \[bu]\ \ \"
1202 .de LI
1203 .IP "" 4
1204 \h'-\w'\*[BU]'u'\*[BU]\c
1207 Convert your font to something groff understands.
1209 This is either a PostScript Type\~1 font in PFA format or a
1210 PostScript Type\~42 font, together with an AFM file.
1213 The very first characters in a PFA file look like this:
1217 .B %!PS-AdobeFont-1.0:
1221 A PFB file has this also in the first line, but the string is
1222 preceded with some binary bytes.
1225 The very first characters in a Type\~42 font file look like this:
1229 .B %!PS-TrueTypeFont
1233 This is a wrapper format for TrueType fonts.
1235 Old PS printers might not support it (this is, they don't have a
1236 built-in TrueType font interpreter).
1239 If your font is in PFB format (such fonts normally have `.pfb' as
1240 the file extension), you might use groff's
1241 .BR \%pfbtops (@MAN1EXT@)
1242 program to convert it to PFA.
1244 For TrueType fonts, try
1245 .B ttftot42
1247 .BR fontforge .
1248 For all other font formats use
1249 .B fontforge
1250 which can convert most outline font formats.
1253 Convert the AFM file to a groff font description file with the
1254 .BR \%afmtodit (@MAN1EXT@)
1255 program.
1257 An example call is
1261 afmtodit Foo-Bar-Bold.afm textmap FBB
1265 which converts the metric file `Foo-Bar-Bold.afm' to the groff
1266 font `FBB'.
1268 If you have a font family which comes with normal, bold, italic,
1269 and bold italic faces, it is recommended to use the letters
1270 .BR R ,
1271 .BR B ,
1272 .BR I ,
1274 .BR BI ,
1275 respectively, as postfixes in the groff font names to make groff's
1276 `.fam' request work.
1278 An example is groff's built-in Times-Roman font: The font family name
1280 .BR T ,
1281 and the groff font names are
1282 .BR TR ,
1283 .BR TB ,
1284 .BR TI ,
1286 .BR TBI .
1289 Install both the groff font description files and the fonts in a
1290 `devps' subdirectory of the font path which groff finds.
1292 See the
1293 .B ENVIRONMENT
1294 section in the
1295 .BR troff (@MAN1EXT@)
1296 man page which lists the actual value of the font path.
1298 Note that groff doesn't use the AFM files (but it is a good idea to
1299 store them anyway).
1302 Register all fonts which must be downloaded to the printer in the
1303 `devps/download' file.
1305 Only the first occurrence of this file in the font path is read.
1307 This means that you should copy the default `download' file to the
1308 first directory in your font path and add your fonts there.
1310 To continue the above example we assume that the PS font name for
1311 Foo-Bar-Bold.pfa is `XY-Foo-Bar-Bold' (the PS font name is stored in the
1312 .B internalname
1313 field in the `FBB' file), thus the following line should be added to
1314 `download'.
1318 .B XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
1323 .SH OLD FONTS
1324 groff versions 1.19.2 and earlier contain a slightly different set of
1325 the 35 Adobe core fonts; the difference is mainly the lack of the `Euro'
1326 glyph and a reduced set of kerning pairs.
1328 For backwards compatibility, these old fonts are installed also in the
1329 directory
1330 .BR @OLDFONTDIR@/devps .
1333 To use them, make sure that
1334 .B grops
1335 finds the fonts before the default system fonts (with the same names):
1336 Either add command line option
1337 .B \-F
1339 .B grops
1342 .B groff \-Tps \-P\-F -P@OLDFONTDIR@ .\|.\|.
1345 or add the directory to groff's font path environment variable
1348 .B GROFF_FONT_PATH=@OLDFONTDIR@
1351 .SH ENVIRONMENT
1354 .B GROPS_PROLOGUE
1355 If this is set to
1356 .IR foo ,
1357 then
1358 .B grops
1359 uses the file
1360 .I foo
1361 (in the font path) instead of the default prologue file
1362 .BR prologue .
1364 The option
1365 .B \-P
1366 overrides this environment variable.
1371 .B GROFF_FONT_PATH
1372 A list of directories in which to search for the
1373 .BI dev name
1374 directory in addition to the default ones.
1377 .BR @g@troff (@MAN1EXT@)
1379 .BR \%groff_font (@MAN5EXT@)
1380 for more details.
1383 .SH FILES
1384 .Tp \w'\fB@FONTDIR@/devps/download'u+2n
1385 .B @FONTDIR@/devps/DESC
1386 Device description file.
1389 .BI @FONTDIR@/devps/ F
1390 Font description file for font
1391 .IR F .
1394 .B @FONTDIR@/devps/download
1395 List of downloadable fonts.
1398 .B @FONTDIR@/devps/text.enc
1399 Encoding used for text fonts.
1402 .B @MACRODIR@/ps.tmac
1403 Macros for use with
1404 .BR grops ;
1405 automatically loaded by
1406 .BR troffrc
1409 .B @MACRODIR@/pspic.tmac
1410 Definition of
1411 .B PSPIC
1412 macro,
1413 automatically loaded by
1414 .BR ps.tmac .
1417 .B @MACRODIR@/psold.tmac
1418 Macros to disable use of characters not present in older
1419 PostScript printers (e.g., `eth' or `thorn').
1422 .BI /tmp/grops XXXXXX
1423 Temporary file.
1426 .SH "SEE ALSO"
1427 .BR \%afmtodit (@MAN1EXT@),
1428 .BR groff (@MAN1EXT@),
1429 .BR @g@troff (@MAN1EXT@),
1430 .BR \%pfbtops (@MAN1EXT@),
1431 .BR \%groff_out (@MAN5EXT@),
1432 .BR \%groff_font (@MAN5EXT@),
1433 .BR \%groff_char (@MAN7EXT@),
1434 .BR \%groff_tmac (@MAN5EXT@)
1437 .URL "http://\:partners.adobe.com/\:public/\:developer/\:en/\:ps/\:5001.DSC_Spec.pdf" \
1438      "PostScript Language Document Structuring Conventions Specification"
1440 .cp \n[grops_C]
1442 .\" Local Variables:
1443 .\" mode: nroff
1444 .\" End: