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
27 .\" Like TP, but if specified indent is more than half
28 .\" the current line-length - indent, use the default indent.
30 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
41 . if '\\*(.T'ps' .ft \\$1
45 .TH GROPS @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
49 grops \- PostScript driver for groff
61 . ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\%\\$2" "\ ]"
62 . el .RB "[\ " "\\$1" "\ ]"
73 .RI "[\ " files\|.\|.\|. "\ ]"
78 It is possible to have whitespace between a command line option and its
84 translates the output of GNU
90 should be invoked by using the groff command
95 .if '@DEVICE@'ps' (Actually, this is the default for groff.)
97 If no files are given,
99 reads the standard input.
105 to read the standard input.
107 PostScript output is written to the standard output.
113 options can be passed to
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.
131 below for a guide how to install fonts for
138 Provide workarounds for older printers, broken spoolers, and previewers.
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.
151 does to make its output acceptable to such programs.
153 A value of\~0 causes grops not to employ any workarounds.
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
164 comment and the first
169 Add\~2 if lines in included files beginning with
171 should be stripped out; this is needed for Sun's pageview previewer.
180 stripped out of included files; this is needed for spoolers that
188 Add\~8 if the first line of the PostScript output should be
192 this is needed when using Sun's Newsprint with a printer that requires
196 Add\~16 if no media size information should be included in the document
197 (this is, neither use
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
217 command in the DESC file.
219 Otherwise the default value is\~0.
232 to the search path for prologue, font, and device description files;
234 is the name of the device, usually
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.
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'
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.
267 Print the document in landscape format.
271 Turn manual feed on for the document.
275 Set physical dimension of output medium.
284 file; it accepts the same arguments as the
289 .B groff_font (@MAN5EXT@)
293 .BI \-P prologue-file
296 (in the font path) as the prologue instead of the default prologue file
299 This option overrides the environment variable
304 Lines should be drawn using a thickness of
306 thousandths of an em.
308 If this option is not given, the line thickness defaults to 0.04\~em.
312 Print the version number.
318 must be in the format output by
319 .BR @g@troff (@MAN1EXT@).
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
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
348 It may also contain a command
350 .BI encoding\ enc_file
353 the PostScript font should be reencoded using the encoding described in
355 this file should consist of a sequence of lines of the form:
362 is the PostScript name of the character,
365 is its position in the encoding expressed as a decimal integer; valid
366 values are in the range 0 to\~255.
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
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.
388 assumes that a character with a groff name of
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.
397 is able to display all glyphs in a PostScript font, not only 256.
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
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
418 must be listed in the file
419 .BR @FONTDIR@/devps/download ;
420 this should consist of lines of the form
429 is the PostScript name of the font,
432 is the name of the file containing the font;
435 and blank lines are ignored;
436 fields may be separated by tabs or spaces;
438 is searched for using the same mechanism that is used
439 for groff font metric files.
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,
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
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.
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
487 %%IncludeResource: font Garamond
490 In this case both Garamond and Garamond-Outline would need to be listed
495 A downloadable font should not include its own name in a
496 .B %%Document\%Supplied\%Resources
506 .BR %%Document\%Needed\%Resources ,
507 .BR %%Document\%Supplied\%Resources ,
508 .BR %%Include\%Resource ,
509 .BR %%Begin\%Resource ,
514 .BR %%Document\%Needed\%Fonts ,
515 .BR %%Document\%Supplied\%Fonts ,
516 .BR %%Include\%Font ,
525 there are styles called
531 mounted at font positions 1 to\~4.
533 The fonts are grouped into families
543 having members in each of these styles:
555 AvantGarde-BookOblique
567 AvantGarde-DemiOblique
639 Helvetica-BoldOblique
651 Helvetica-Narrow-Oblique
657 Helvetica-Narrow-Bold
663 Helvetica-Narrow-BoldOblique
669 NewCenturySchlbk-Roman
675 NewCenturySchlbk-Italic
681 NewCenturySchlbk-Bold
687 NewCenturySchlbk-BoldItalic
740 There is also the following font which is not a member of a family:
746 ZapfChancery-MediumItalic
751 There are also some special fonts called
753 for the PS Symbol font, and
755 containing slanted lowercase Greek letters taken from PS Symbol.
757 Zapf Dingbats is available as
759 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
760 direction) is available as
762 most characters in these fonts are unnamed and must be accessed using
766 The default color for
770 is black; for colors defined in the `rgb' color space
772 is used, for `cmy' and `cmyk'
779 is a PostScript LanguageLevel\~2 command and thus not available on some
784 understands various X\~commands produced using the
788 only interprets commands that begin with a
793 .BI \[rs]X'ps:\ exec\ code '
794 This executes the arbitrary PostScript commands in
797 The PostScript currentpoint is set to the position of the
799 command before executing
802 The origin is at the top left corner of the page,
803 and y\~coordinates increase down the page.
807 is defined that converts groff units
808 to the coordinate system in effect (provided the user doesn't change the
819 \[rs]X'ps: exec \[rs]nx u 0 rlineto stroke'
824 draws a horizontal line one inch long.
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
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.
844 escape sequence with an argument that names a macro,
846 can extend over multiple lines.
857 \&\[rs]nx u 0 rlineto
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
876 wraps user-specified PostScript code into a dictionary, nothing more.
878 In particular, it doesn't start and end the inserted code with
884 This must be supplied by the user, if necessary.
889 .BI \[rs]X'ps:\ file\ name '
890 This is the same as the
892 command except that the PostScript code is read from file
896 .BI \[rs]X'ps:\ def\ code '
897 Place a PostScript definition contained in
901 There should be at most one definition per
905 Long definitions can be split over several
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
919 escape sequence with an argument that names a macro,
921 can extend over multiple lines.
924 .BI \[rs]X'ps:\ mdef\ n\ code '
934 needs to know how many definitions
937 so that it can create an appropriately sized PostScript dictionary
941 .BI \[rs]X'ps:\ import\ file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
942 Import a PostScript graphic from
951 give the bounding box of the graphic in the default PostScript
952 coordinate system; they should all be integers;
956 are the x and y\~coordinates of the lower left
957 corner of the graphic;
961 are the x and y\~coordinates of the upper right corner of the graphic;
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
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
981 command are not interpreted by
983 so vertical space for the graphic is not automatically added,
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
994 comment, then the bounding box can be automatically
995 extracted from within groff by using the
1001 .BR groff_tmac (@MAN5EXT@)
1002 for a description of the
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
1016 These commands are intended for use when output from
1018 is previewed before being processed with
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
1030 is not able to display a proper
1032 character because the standard X11 fonts do not provide it;
1033 this problem can be overcome by executing the following
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
1048 is unable to display the
1050 character and draws the line,
1056 and ignores the line (this code is already in file
1058 which is loaded if a document intended for
1065 If a PostScript procedure
1067 has been defined via a
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
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
1094 Or, to cause lines and polygons to be drawn with square linecaps
1095 and mitered linejoins instead of the round linecaps and linejoins
1105 /BPhook { 2 setlinecap 0 setlinejoin } def
1112 (square linecaps, as opposed to butt linecaps (0 setlinecap),
1113 give true corners in boxed tables even though the lines are
1117 .SS Encapsulated PostScript
1119 itself doesn't emit bounding box information.
1121 With the help of Ghostscript the following simple script,
1123 produces an encapsulated PS file.
1130 groff \-P\-b16 $1 >$1.ps
1131 gs \-dNOPAUSE \-sDEVICE=bbox \-\- $1.ps 2>$1.bbox
1133 | sed \-e "/\[ha]%%Orientation/r$1.bbox" \[rs]
1134 \-e "/\[ha]%!PS-Adobe-3.0/s/$/ EPSF-3.0/" >$1.eps
1154 .SS TrueType and other font formats
1155 TrueType fonts can be used with
1157 if converted first to
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
1169 Yet, the easiest method involves the use of the application
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
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,
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
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
1248 For all other font formats use
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@)
1261 afmtodit Foo-Bar-Bold.afm textmap FBB
1265 which converts the metric file `Foo-Bar-Bold.afm' to the groff
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
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
1281 and the groff font names are
1289 Install both the groff font description files and the fonts in a
1290 `devps' subdirectory of the font path which groff finds.
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
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
1313 field in the `FBB' file), thus the following line should be added to
1318 .B XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
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
1330 .BR @OLDFONTDIR@/devps .
1333 To use them, make sure that
1335 finds the fonts before the default system fonts (with the same names):
1336 Either add command line option
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@
1361 (in the font path) instead of the default prologue file
1366 overrides this environment variable.
1372 A list of directories in which to search for the
1374 directory in addition to the default ones.
1377 .BR @g@troff (@MAN1EXT@)
1379 .BR \%groff_font (@MAN5EXT@)
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
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
1405 automatically loaded by
1409 .B @MACRODIR@/pspic.tmac
1413 automatically loaded by
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
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"
1442 .\" Local Variables: