1 .TH GROPS @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
3 grops \- PostScript driver for groff
8 Copyright \[co] 1989-2014 Free Software Foundation, Inc.
10 Permission is granted to make and distribute verbatim copies of
11 this manual provided the copyright notice and this permission notice
12 are preserved on all copies.
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
19 Permission is granted to copy and distribute translations of this
20 manual into another language, under the above conditions for modified
21 versions, except that this permission notice may be included in
22 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
35 . if '\\*(.T'ps' .ft \\$1
36 . if '\\*(.T'pdf' .ft \\$1
39 .\" --------------------------------------------------------------------
41 .\" --------------------------------------------------------------------
57 .\" --------------------------------------------------------------------
59 .\" --------------------------------------------------------------------
62 translates the output of GNU
68 should be invoked by using the groff command with a
72 .if '@DEVICE@'ps' (Actually, this is the default for groff.)
74 If no files are given,
76 reads the standard input.
82 to read the standard input.
84 PostScript output is written to the standard output.
90 options can be passed to
101 doesn\[aq]t produce a valid document structure (conforming to the
102 Document Structuring Convention) if called with multiple file
105 To print such concatenated output it is necessary to deactivate DSC
106 handling in the printing program or previewer.
110 below for a guide how to install fonts for
114 .\" --------------------------------------------------------------------
116 .\" --------------------------------------------------------------------
118 It is possible to have whitespace between a command line option and its
124 Provide workarounds for older printers, broken spoolers, and previewers.
128 produces output at PostScript LanguageLevel\~2 that conforms to the
129 Document Structuring Conventions version 3.0.
131 Some older printers, spoolers, and previewers can\[aq]t handle such
138 does to make its output acceptable to such programs.
140 A value of\~0 causes grops not to employ any workarounds.
144 .B %%Begin\%Document\%Setup
146 .B %%End\%Document\%Setup
147 comments should be generated;
148 this is needed for early versions of TranScript that get confused by
151 comment and the first
156 Add\~2 if lines in included files beginning with
158 should be stripped out; this is needed for Sun\[aq]s pageview
168 stripped out of included files; this is needed for spoolers that
169 don\[aq]t understand the
176 Add\~8 if the first line of the PostScript output should be
180 this is needed when using Sun\[aq]s Newsprint with a printer that
181 requires page reversal.
184 Add\~16 if no media size information should be included in the
185 document (this is, neither use
191 This was the behaviour of groff version 1.18.1 and earlier; it is
192 needed for older printers which don\[aq]t understand PostScript
195 It is also necessary if the output is further processed to get an
196 encapsulated PS (EPS) file \[en] see below.
199 The default value can be specified by a
206 command in the DESC file.
208 Otherwise the default value is\~0.
221 to the search path for prologue, font, and device description files;
223 is the name of the device, usually
228 Guess the page length.
230 This generates PostScript code that guesses the page length.
232 The guess is correct only if the imageable area is vertically
233 centered on the page.
235 This option allows you to generate documents that can be printed
236 both on letter (8.5\[mu]11) paper and on A4 paper without change.
240 This option may be used to add a directory to the search path for
241 files on the command line and files named in
242 .B \[rs]X'ps: import'
247 The search path is initialized with the current directory.
249 This option may be specified more than once; the directories are then
250 searched in the order specified (but before the current directory).
252 If you want to make the current directory be read before other directories,
255 at the appropriate place.
258 No directory search is performed for files with an absolute file name.
262 Print the document in landscape format.
266 Turn manual feed on for the document.
270 Set physical dimension of output medium.
279 file; it accepts the same arguments as the
284 .B groff_font (@MAN5EXT@)
288 .BI \-P prologue-file
291 (in the font path) as the prologue instead of the default prologue file
294 This option overrides the environment variable
299 Lines should be drawn using a thickness of
301 thousandths of an em.
303 If this option is not given, the line thickness defaults to 0.04\~em.
307 Print the version number.
310 .\" --------------------------------------------------------------------
312 .\" --------------------------------------------------------------------
316 must be in the format output by
317 .BR @g@troff (@MAN1EXT@).
320 .BR groff_out (@MAN5EXT@).
323 In addition, the device and font description files for the device used
324 must meet certain requirements:
326 The resolution must be an integer multiple of\~72 times the
331 device uses a resolution of 72000 and a sizescale of 1000.
335 The device description file must contain a valid paper size; see
336 .BR groff_font (@MAN5EXT@)
337 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.
398 is able to display all glyphs in a PostScript font, not only 256.
400 (or the default encoding if no encoding file specified) just defines the
401 order of glyphs for the first 256 characters; all other glyphs are
402 accessed with additional encoding vectors which
409 can automatically include the downloadable fonts necessary
410 to print the document.
412 Such fonts must be in PFA format.
415 .BR \%pfbtops (@MAN1EXT@)
416 to convert a Type\~1 font in PFB format.
418 Any downloadable fonts which should, when required, be included by
420 must be listed in the file
421 .BR @FONTDIR@/devps/download ;
422 this should consist of lines of the form
432 is the PostScript name of the font,
435 is the name of the file containing the font;
438 and blank lines are ignored;
439 fields may be separated by tabs or spaces;
441 is searched for using the same mechanism that is used
442 for groff font metric files.
446 file itself is also searched for using this mechanism;
447 currently, only the first found file in the font path is used.
451 If the file containing a downloadable font or imported document
452 conforms to the Adobe Document Structuring Conventions,
455 interprets any comments in the files sufficiently to ensure that its
456 own output is conforming.
458 It also supplies any needed font resources that are listed in the
461 as well as any needed file resources.
463 It is also able to handle inter-resource dependencies.
465 For example, suppose that you have a downloadable font called
466 Garamond, and also a downloadable font called Garamond-Outline which
467 depends on Garamond (typically it would be defined to copy
468 Garamond\[aq]s font dictionary, and change the PaintType), then it is
469 necessary for Garamond to appear before Garamond-Outline in the
473 handles this automatically provided that the downloadable font file
474 for Garamond-Outline indicates its dependence on Garamond by means of
475 the Document Structuring Conventions, for example by beginning with
480 %!PS-Adobe-3.0 Resource-Font
483 %%DocumentNeededResources: font Garamond
489 %%IncludeResource: font Garamond
493 In this case both Garamond and Garamond-Outline would need to be listed
498 A downloadable font should not include its own name in a
499 .B %%Document\%Supplied\%Resources
510 .BR %%Document\%Needed\%Resources ,
511 .BR %%Document\%Supplied\%Resources ,
512 .BR %%Include\%Resource ,
513 .BR %%Begin\%Resource ,
518 .BR %%Document\%Needed\%Fonts ,
519 .BR %%Document\%Supplied\%Fonts ,
520 .BR %%Include\%Font ,
530 there are styles called
536 mounted at font positions 1 to\~4.
538 The fonts are grouped into families
548 having members in each of these styles:
560 AvantGarde-BookOblique
572 AvantGarde-DemiOblique
644 Helvetica-BoldOblique
656 Helvetica-Narrow-Oblique
662 Helvetica-Narrow-Bold
668 Helvetica-Narrow-BoldOblique
674 NewCenturySchlbk-Roman
680 NewCenturySchlbk-Italic
686 NewCenturySchlbk-Bold
692 NewCenturySchlbk-BoldItalic
746 There is also the following font which is not a member of a family:
752 ZapfChancery-MediumItalic
758 There are also some special fonts called
760 for the PS Symbol font, and
762 containing slanted lowercase Greek letters taken from PS Symbol.
764 Zapf Dingbats is available as
766 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
767 direction) is available as
769 most characters in these fonts are unnamed and must be accessed using
774 The default color for
778 is black; for colors defined in the \[oq]rgb\[cq] color space
780 is used, for \[oq]cmy\[cq] and \[oq]cmyk\[cq]
782 and for \[oq]gray\[cq]
787 is a PostScript LanguageLevel\~2 command and thus not available on some
793 understands various X\~commands produced using the
797 only interprets commands that begin with a
802 .BI \[rs]X'ps:\ exec\ code '
803 This executes the arbitrary PostScript commands in
806 The PostScript currentpoint is set to the position of the
808 command before executing
811 The origin is at the top left corner of the page,
812 and y\~coordinates increase down the page.
816 is defined that converts groff units to the coordinate system in
817 effect (provided the user doesn\[aq]t change the scale).
827 \[rs]X'ps: exec \[rs]nx u 0 rlineto stroke'
832 draws a horizontal line one inch long.
835 may make changes to the graphics state,
836 but any changes persist only to the end of the page.
838 A dictionary containing the definitions specified by the
842 is on top of the dictionary stack.
844 If your code adds definitions to this dictionary,
845 you should allocate space for them using
846 .BI \[rs]X'ps\ mdef \ n '\fR.
848 Any definitions persist only until the end of the page.
852 escape sequence with an argument that names a macro,
854 can extend over multiple lines.
865 \&\[rs]nx u 0 rlineto
873 is another way to draw a horizontal line one inch long.
875 Note the single backslash before \[oq]nx\[cq] \[en] the only reason to
876 use a number register while defining the macro \[oq]y\[cq] is to
877 convert a user-specified dimension \[oq]1i\[cq] to internal groff
878 units which are in turn converted to PS units with the
885 wraps user-specified PostScript code into a dictionary, nothing more.
887 In particular, it doesn\[aq]t start and end the inserted code with
893 This must be supplied by the user, if necessary.
898 .BI \[rs]X'ps:\ file\ name '
899 This is the same as the
901 command except that the PostScript code is read from file
905 .BI \[rs]X'ps:\ def\ code '
906 Place a PostScript definition contained in
910 There should be at most one definition per
914 Long definitions can be split over several
919 arguments are simply joined together separated by newlines.
921 The definitions are placed in a dictionary which is automatically
922 pushed on the dictionary stack when an
928 escape sequence with an argument that names a macro,
930 can extend over multiple lines.
933 .BI \[rs]X'ps:\ mdef\ n\ code '
943 needs to know how many definitions
946 so that it can create an appropriately sized PostScript dictionary
950 .BI \[rs]X'ps:\ import\ file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
951 Import a PostScript graphic from
960 give the bounding box of the graphic in the default PostScript
961 coordinate system; they should all be integers;
965 are the x and y\~coordinates of the lower left
966 corner of the graphic;
970 are the x and y\~coordinates of the upper right corner of the graphic;
974 are integers that give the desired width and height in groff
975 units of the graphic.
978 The graphic is scaled so that it has this width and height
979 and translated so that the lower left corner of the graphic is
980 located at the position associated with
984 If the height argument is omitted it is scaled uniformly in the
985 x and y\~directions so that it has the specified width.
988 Note that the contents of the
990 command are not interpreted by
992 so vertical space for the graphic is not automatically added,
997 arguments are not allowed to have attached scaling indicators.
1000 If the PostScript file complies with the Adobe Document Structuring
1001 Conventions and contains a
1003 comment, then the bounding box can be automatically
1004 extracted from within groff by using the
1010 .BR groff_tmac (@MAN5EXT@)
1011 for a description of the
1013 macro which provides a convenient high-level interface for inclusion of
1014 PostScript graphics.
1017 .B \[rs]X'ps:\ invis'
1019 .B \[rs]X'ps:\ endinvis'
1020 No output is generated for text and drawing commands
1021 that are bracketed with these
1025 These commands are intended for use when output from
1027 is previewed before being processed with
1029 if the previewer is unable to display certain characters
1030 or other constructs, then other substitute characters or constructs
1031 can be used for previewing by bracketing them with these
1040 is not able to display a proper
1042 character because the standard X11 fonts do not provide it;
1043 this problem can be overcome by executing the following
1049 \&.char \[rs](em \[rs]X'ps: invis'\[rs]
1050 \[rs]Z'\[rs]v'-.25m'\[rs]h'.05m'\[rs]D'l .9m 0'\[rs]h'.05m''\[rs]
1051 \[rs]X'ps: endinvis'\[rs](em
1059 is unable to display the
1061 character and draws the line,
1067 and ignores the line (this code is already in file
1069 which is loaded if a document intended for
1077 If a PostScript procedure
1079 has been defined via a
1080 .RB \[oq] ps:\ def \[cq]
1082 .RB \[oq] ps:\ mdef \[cq]
1083 device command, it is executed at the beginning of every page (before
1084 anything is drawn or written by groff).
1086 For example, to underlay the page contents with the word
1087 \[oq]DRAFT\[cq] in light gray, you might use
1095 { gsave .9 setgray clippath pathbbox exch 2 copy
1096 .5 mul exch .5 mul translate atan rotate pop pop
1097 /NewCenturySchlbk-Roman findfont 200 scalefont setfont
1098 (DRAFT) dup stringwidth pop \-.5 mul \-70 moveto show
1107 Or, to cause lines and polygons to be drawn with square linecaps
1108 and mitered linejoins instead of the round linecaps and linejoins
1118 /BPhook { 2 setlinecap 0 setlinejoin } def
1125 (square linecaps, as opposed to butt linecaps (0 setlinecap),
1126 give true corners in boxed tables even though the lines are
1130 .\" --------------------------------------------------------------------
1131 .SS Encapsulated PostScript
1132 .\" --------------------------------------------------------------------
1135 itself doesn\[aq]t emit bounding box information.
1137 With the help of Ghostscript the following simple script,
1139 produces an encapsulated PS file.
1147 groff \-P\-b16 $1 > $1.ps
1148 gs \-dNOPAUSE \-sDEVICE=bbox \-\- $1.ps 2> $1.bbox
1149 sed \-e "/\[ha]%%Orientation/r $1.bbox" \[rs]
1150 \-e "/\[ha]%!PS-Adobe-3.0/s/$/ EPSF-3.0/" $1.ps > $1.eps
1171 .\" --------------------------------------------------------------------
1172 .SS TrueType and other font formats
1173 .\" --------------------------------------------------------------------
1175 TrueType fonts can be used with
1177 if converted first to
1179 format, a special PostScript wrapper equivalent to the PFA format
1181 .BR \%pfbtops (@MAN1EXT@).
1183 There are several different methods to generate a type42 wrapper and
1184 most of them involve the use of a PostScript interpreter such as
1185 Ghostscript \[en] see
1190 Yet, the easiest method involves the use of the application
1195 (version 1.3.1) to generate type42
1196 font wrappers and well-formed AFM files that can be fed to
1198 .BR \%afmtodit (@MAN1EXT@)
1199 script to create appropriate metric files.
1201 The resulting font wrappers should be added to the
1205 source code can be downloaded from
1206 .UR ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/
1207 ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/
1212 Another solution for creating type42 wrappers is to use FontForge,
1214 .UR http://\:fontforge.sf.net
1215 http://\:fontforge.sf.net
1217 This font editor can convert most outline font formats.
1220 .\" --------------------------------------------------------------------
1221 .SH "FONT INSTALLATION"
1222 .\" --------------------------------------------------------------------
1224 This section gives a summary of the above explanations; it can serve
1225 as a step-by-step font installation guide for
1231 \h'-\w'\*[BU]'u'\*[BU]\c
1234 Convert your font to something groff understands.
1236 This is either a PostScript Type\~1 font in PFA format or a PostScript
1237 Type\~42 font, together with an AFM file.
1240 The very first characters in a PFA file look like this:
1244 .B %!PS-AdobeFont-1.0:
1248 A PFB file has this also in the first line, but the string is
1249 preceded with some binary bytes.
1252 The very first characters in a Type\~42 font file look like this:
1256 .B %!PS-TrueTypeFont
1260 This is a wrapper format for TrueType fonts.
1262 Old PS printers might not support it (this is, they don\[aq]t have a
1263 built-in TrueType font interpreter).
1266 If your font is in PFB format (such fonts normally have \[oq].pfb\[cq]
1267 as the file extension), you might use groff\[aq]s
1268 .BR \%pfbtops (@MAN1EXT@)
1269 program to convert it to PFA.
1271 For TrueType fonts, try
1275 For all other font formats use
1277 which can convert most outline font formats.
1280 Convert the AFM file to a groff font description file with the
1281 .BR \%afmtodit (@MAN1EXT@)
1288 afmtodit Foo-Bar-Bold.afm textmap FBB
1292 which converts the metric file \[oq]Foo-Bar-Bold.afm\[cq] to the groff
1295 If you have a font family which comes with normal, bold, italic,
1296 and bold italic faces, it is recommended to use the letters
1302 respectively, as postfixes in the groff font names to make groff\[aq]s
1303 \[oq].fam\[cq] request work.
1305 An example is groff\[aq]s built-in Times-Roman font: The font family
1308 and the groff font names are
1316 Install both the groff font description files and the fonts in a
1317 \[oq]devps\[cq] subdirectory of the font path which groff finds.
1322 .BR troff (@MAN1EXT@)
1323 man page which lists the actual value of the font path.
1325 Note that groff doesn\[aq]t use the AFM files (but it is a good idea
1326 to store them anyway).
1329 Register all fonts which must be downloaded to the printer in the
1330 \[oq]devps/download\[cq] file.
1332 Only the first occurrence of this file in the font path is read.
1334 This means that you should copy the default \[oq]download\[cq] file to
1335 the first directory in your font path and add your fonts there.
1337 To continue the above example we assume that the PS font name for
1338 Foo-Bar-Bold.pfa is \[oq]XY-Foo-Bar-Bold\[cq] (the PS font name is
1341 field in the \[oq]FBB\[cq] file), thus the following line should be
1342 added to \[cq]download\[cq].
1346 .B XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
1351 .\" --------------------------------------------------------------------
1353 .\" --------------------------------------------------------------------
1355 groff versions 1.19.2 and earlier contain a slightly different set of
1356 the 35 Adobe core fonts; the difference is mainly the lack of the
1357 \[oq]Euro\[cq] glyph and a reduced set of kerning pairs.
1359 For backwards compatibility, these old fonts are installed also in the
1362 .BR @OLDFONTDIR@/devps
1369 To use them, make sure that
1371 finds the fonts before the default system fonts (with the same names):
1372 Either add command line option
1378 .B groff \-Tps \-P\-F \-P@OLDFONTDIR@ .\|.\|.
1381 or add the directory to groff\[aq]s font path environment variable
1384 .B GROFF_FONT_PATH=@OLDFONTDIR@
1387 .\" --------------------------------------------------------------------
1389 .\" --------------------------------------------------------------------
1400 (in the font path) instead of the default prologue file
1405 overrides this environment variable.
1411 A list of directories in which to search for the
1413 directory in addition to the default ones.
1416 .BR @g@troff (@MAN1EXT@)
1418 .BR \%groff_font (@MAN5EXT@)
1422 .\" --------------------------------------------------------------------
1424 .\" --------------------------------------------------------------------
1426 .Tp \w'\fB@FONTDIR@/devps/download'u+2n
1427 .B @FONTDIR@/devps/DESC
1428 Device description file.
1431 .BI @FONTDIR@/devps/ F
1432 Font description file for font
1436 .B @FONTDIR@/devps/download
1437 List of downloadable fonts.
1440 .B @FONTDIR@/devps/text.enc
1441 Encoding used for text fonts.
1444 .B @MACRODIR@/ps.tmac
1447 automatically loaded by
1451 .B @MACRODIR@/pspic.tmac
1455 automatically loaded by
1459 .B @MACRODIR@/psold.tmac
1460 Macros to disable use of characters not present in older
1461 PostScript printers (e.g., \[oq]eth\[cq] or \[oq]thorn\[cq]).
1464 .BI /tmp/grops XXXXXX
1467 .BR groff (@MAN1EXT@)
1468 for details on the location of temporary files.
1471 .\" --------------------------------------------------------------------
1473 .\" --------------------------------------------------------------------
1475 .BR \%afmtodit (@MAN1EXT@),
1476 .BR groff (@MAN1EXT@),
1477 .BR @g@troff (@MAN1EXT@),
1478 .BR \%pfbtops (@MAN1EXT@),
1479 .BR \%groff_out (@MAN5EXT@),
1480 .BR \%groff_font (@MAN5EXT@),
1481 .BR \%groff_char (@MAN7EXT@),
1482 .BR \%groff_tmac (@MAN5EXT@)
1486 .UR http://\:partners.adobe.com/\:public/\:developer/\:en/\:ps/\:5001.DSC_Spec.pdf
1487 PostScript Language Document Structuring Conventions Specification
1491 .\" --------------------------------------------------------------------
1493 .\" --------------------------------------------------------------------
1497 .\" Local Variables:
projects / platform / upstream / groff.git / blob