1 .TH GROPS @MAN1EXT@ "@MDATE@" "groff @VERSION@"
3 grops \- PostScript driver for groff
6 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
11 .\" ====================================================================
13 .\" ====================================================================
15 .\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
17 .\" Permission is granted to make and distribute verbatim copies of this
18 .\" manual provided the copyright notice and this permission notice are
19 .\" preserved on all copies.
21 .\" Permission is granted to copy and distribute modified versions of
22 .\" this manual under the conditions for verbatim copying, provided that
23 .\" the entire resulting derived work is distributed under the terms of
24 .\" a permission notice identical to this one.
26 .\" Permission is granted to copy and distribute translations of this
27 .\" manual into another language, under the above conditions for
28 .\" modified versions, except that this permission notice may be
29 .\" included in translations approved by the Free Software Foundation
30 .\" instead of in the original English.
34 . if '\\*(.T'ps' .ft \\$1
35 . if '\\*(.T'pdf' .ft \\$1
38 .\" ====================================================================
40 .\" ====================================================================
56 .\" ====================================================================
58 .\" ====================================================================
61 translates the output of GNU
67 should be invoked by using the groff command with a
71 .if '@DEVICE@'ps' (Actually, this is the default for groff.)
73 If no files are given,
75 reads the standard input.
81 to read the standard input.
83 PostScript output is written to the standard output.
89 options can be passed to
100 doesn't produce a valid document structure (conforming to the
101 Document Structuring Convention) if called with multiple file
104 To print such concatenated output it is necessary to deactivate DSC
105 handling in the printing program or previewer.
107 See section \[lq]Font Installation\[rq] below for a guide how to install
112 .\" ====================================================================
114 .\" ====================================================================
116 Whitespace is permitted between a command-line option and its argument.
121 Provide workarounds for older printers, broken spoolers, and previewers.
125 produces output at PostScript LanguageLevel\~2 that conforms to the
126 Document Structuring Conventions version 3.0.
128 Some older printers, spoolers, and previewers can't handle such
135 does to make its output acceptable to such programs.
137 A value of\~0 causes grops not to employ any workarounds.
141 .B %%Begin\%Document\%Setup
143 .B %%End\%Document\%Setup
144 comments should be generated;
145 this is needed for early versions of TranScript that get confused by
148 comment and the first
153 Add\~2 if lines in included files beginning with
155 should be stripped out; this is needed for Sun's pageview
165 stripped out of included files; this is needed for spoolers that
173 Add\~8 if the first line of the PostScript output should be
177 this is needed when using Sun's Newsprint with a printer that
178 requires page reversal.
181 Add\~16 if no media size information should be included in the
182 document (this is, neither use
188 This was the behaviour of groff version 1.18.1 and earlier; it is
189 needed for older printers which don't understand PostScript
192 It is also necessary if the output is further processed to get an
193 encapsulated PS (EPS) file \[en] see below.
196 The default value can be specified by a
207 Otherwise the default value is\~0.
220 to the search path for prologue, font, and device description files;
222 is the name of the device, usually
227 Guess the page length.
229 This generates PostScript code that guesses the page length.
231 The guess is correct only if the imageable area is vertically
232 centered on the page.
234 This option allows you to generate documents that can be printed
235 both on letter (8.5\[mu]11) paper and on A4 paper without change.
239 This option may be used to add a directory to the search path for
240 files on the command line and files named in
241 .B \[rs]X'ps: import'
246 The search path is initialized with the current directory.
248 This option may be specified more than once; the directories are then
249 searched in the order specified (but before the current directory).
251 If you want to make the current directory be read before other directories,
254 at the appropriate place.
257 No directory search is performed for files with an absolute file name.
261 Print the document in landscape format.
265 Turn manual feed on for the document.
269 Set physical dimension of output medium.
278 file; it accepts the same arguments as the
283 .B groff_font (@MAN5EXT@)
287 .BI \-P prologue-file
290 (in the font path) as the prologue instead of the default prologue file
293 This option overrides the environment variable
298 Lines should be drawn using a thickness of
300 thousandths of an em.
302 If this option is not given, the line thickness defaults to 0.04\~em.
306 Print the version number.
309 .\" ====================================================================
311 .\" ====================================================================
315 must be in the format output by
316 .BR @g@troff (@MAN1EXT@).
319 .BR groff_out (@MAN5EXT@).
322 In addition, the device and font description files for the device used
323 must meet certain requirements:
325 The resolution must be an integer multiple of\~72 times the
330 device uses a resolution of 72000 and a sizescale of 1000.
334 The device description file must contain a valid paper size; see
335 .BR groff_font (@MAN5EXT@)
336 for more information.
340 Each font description file must contain a command
342 .BI internalname\ psname
344 which says that the PostScript name of the font is
347 It may also contain a command
349 .BI encoding\ enc_file
352 the PostScript font should be reencoded using the encoding described in
354 this file should consist of a sequence of lines of the form:
361 is the PostScript name of the character,
364 is its position in the encoding expressed as a decimal integer; valid
365 values are in the range 0 to\~255.
369 and blank lines are ignored.
371 The code for each character given in the font file must correspond
372 to the code for the character in encoding file, or to the code in the default
373 encoding for the font if the PostScript font is not to be reencoded.
375 This code can be used with the
379 to select the character,
380 even if the character does not have a groff name.
382 Every character in the font file must exist in the PostScript font, and
383 the widths given in the font file must match the widths used
384 in the PostScript font.
387 assumes that a character with a groff name of
389 is blank (makes no marks on the page);
390 it can make use of such a character to generate more efficient and
391 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
408 can automatically include the downloadable fonts necessary
409 to print the document.
411 Such fonts must be in PFA format.
414 .BR \%pfbtops (@MAN1EXT@)
415 to convert a Type\~1 font in PFB format.
417 Any downloadable fonts which should, when required, be included by
419 must be listed in the file
420 .IR @FONTDIR@/devps/download ;
421 this should consist of lines of the form
431 is the PostScript name of the font,
434 is the name of the file containing the font;
437 and blank lines are ignored;
438 fields may be separated by tabs or spaces;
440 is searched for using the same mechanism that is used
441 for groff font metric files.
445 file itself is also searched for using this mechanism;
446 currently, only the first found file in the font path is used.
450 If the file containing a downloadable font or imported document
451 conforms to the Adobe Document Structuring Conventions,
454 interprets any comments in the files sufficiently to ensure that its
455 own output is conforming.
457 It also supplies any needed font resources that are listed in the
460 as well as any needed file resources.
462 It is also able to handle inter-resource dependencies.
464 For example, suppose that you have a downloadable font called
465 Garamond, and also a downloadable font called Garamond-Outline which
466 depends on Garamond (typically it would be defined to copy
467 Garamond's font dictionary, and change the PaintType), then it is
468 necessary for Garamond to appear before Garamond-Outline in the
472 handles this automatically provided that the downloadable font file
473 for Garamond-Outline indicates its dependence on Garamond by means of
474 the Document Structuring Conventions, for example by beginning with
479 %!PS-Adobe-3.0 Resource-Font
482 %%DocumentNeededResources: font Garamond
488 %%IncludeResource: font Garamond
492 In this case both Garamond and Garamond-Outline would need to be listed
497 A downloadable font should not include its own name in a
498 .B %%Document\%Supplied\%Resources
509 .BR %%Document\%Needed\%Resources ,
510 .BR %%Document\%Supplied\%Resources ,
511 .BR %%Include\%Resource ,
512 .BR %%Begin\%Resource ,
517 .BR %%Document\%Needed\%Fonts ,
518 .BR %%Document\%Supplied\%Fonts ,
519 .BR %%Include\%Font ,
529 there are styles called
535 mounted at font positions 1 to\~4.
537 The fonts are grouped into families
547 having members in each of these styles:
559 AvantGarde-BookOblique
571 AvantGarde-DemiOblique
643 Helvetica-BoldOblique
655 Helvetica-Narrow-Oblique
661 Helvetica-Narrow-Bold
667 Helvetica-Narrow-BoldOblique
673 NewCenturySchlbk-Roman
679 NewCenturySchlbk-Italic
685 NewCenturySchlbk-Bold
691 NewCenturySchlbk-BoldItalic
745 There is also the following font which is not a member of a family:
751 ZapfChancery-MediumItalic
757 There are also some special fonts called
759 for the PS Symbol font, and
761 containing slanted lowercase Greek letters taken from PS Symbol.
763 Zapf Dingbats is available as
765 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
766 direction) is available as
768 most characters in these fonts are unnamed and must be accessed using
773 The default color for
777 is black; for colors defined in the \[oq]rgb\[cq] color space
779 is used, for \[oq]cmy\[cq] and \[oq]cmyk\[cq]
781 and for \[oq]gray\[cq]
786 is a PostScript LanguageLevel\~2 command and thus not available on some
792 understands various X\~commands produced using the
796 only interprets commands that begin with a
801 .BI \[rs]X'ps:\ exec\ code '
802 This executes the arbitrary PostScript commands in
805 The PostScript currentpoint is set to the position of the
807 command before executing
810 The origin is at the top left corner of the page,
811 and y\~coordinates increase down the page.
815 is defined that converts groff units to the coordinate system in
816 effect (provided the user doesn't change the scale).
826 \[rs]X'ps: exec \[rs]nx u 0 rlineto stroke'
831 draws a horizontal line one inch long.
834 may make changes to the graphics state,
835 but any changes persist only to the end of the page.
837 A dictionary containing the definitions specified by the
841 is on top of the dictionary stack.
843 If your code adds definitions to this dictionary,
844 you should allocate space for them using
845 .BI \[rs]X'ps\ mdef \ n '\fR.
847 Any definitions persist only until the end of the page.
851 escape sequence with an argument that names a macro,
853 can extend over multiple lines.
864 \&\[rs]nx u 0 rlineto
872 is another way to draw a horizontal line one inch long.
874 Note the single backslash before \[oq]nx\[cq] \[en] the only reason to
875 use a number register while defining the macro \[oq]y\[cq] is to
876 convert a user-specified dimension \[oq]1i\[cq] to internal groff
877 units which are in turn converted to PS units with the
884 wraps user-specified PostScript code into a dictionary, nothing more.
886 In particular, it doesn't start and end the inserted code with
892 This must be supplied by the user, if necessary.
897 .BI \[rs]X'ps:\ file\ name '
898 This is the same as the
900 command except that the PostScript code is read from file
904 .BI \[rs]X'ps:\ def\ code '
905 Place a PostScript definition contained in
909 There should be at most one definition per
913 Long definitions can be split over several
918 arguments are simply joined together separated by newlines.
920 The definitions are placed in a dictionary which is automatically
921 pushed on the dictionary stack when an
927 escape sequence with an argument that names a macro,
929 can extend over multiple lines.
932 .BI \[rs]X'ps:\ mdef\ n\ code '
942 needs to know how many definitions
945 so that it can create an appropriately sized PostScript dictionary
949 .BI \[rs]X'ps:\ import\ file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
950 Import a PostScript graphic from
959 give the bounding box of the graphic in the default PostScript
960 coordinate system; they should all be integers;
964 are the x and y\~coordinates of the lower left
965 corner of the graphic;
969 are the x and y\~coordinates of the upper right corner of the graphic;
973 are integers that give the desired width and height in groff
974 units of the graphic.
977 The graphic is scaled so that it has this width and height
978 and translated so that the lower left corner of the graphic is
979 located at the position associated with
983 If the height argument is omitted it is scaled uniformly in the
984 x and y\~directions so that it has the specified width.
987 Note that the contents of the
989 command are not interpreted by
991 so vertical space for the graphic is not automatically added,
996 arguments are not allowed to have attached scaling indicators.
999 If the PostScript file complies with the Adobe Document Structuring
1000 Conventions and contains a
1002 comment, then the bounding box can be automatically
1003 extracted from within groff by using the
1009 .BR groff_tmac (@MAN5EXT@)
1010 for a description of the
1012 macro which provides a convenient high-level interface for inclusion of
1013 PostScript graphics.
1016 .B \[rs]X'ps:\ invis'
1018 .B \[rs]X'ps:\ endinvis'
1019 No output is generated for text and drawing commands
1020 that are bracketed with these
1024 These commands are intended for use when output from
1026 is previewed before being processed with
1028 if the previewer is unable to display certain characters
1029 or other constructs, then other substitute characters or constructs
1030 can be used for previewing by bracketing them with these
1039 is not able to display a proper
1041 character because the standard X11 fonts do not provide it;
1042 this problem can be overcome by executing the following
1048 \&.char \[rs](em \[rs]X'ps: invis'\[rs]
1049 \[rs]Z'\[rs]v'-.25m'\[rs]h'.05m'\[rs]D'l .9m 0'\[rs]h'.05m''\[rs]
1050 \[rs]X'ps: endinvis'\[rs](em
1058 is unable to display the
1060 character and draws the line,
1066 and ignores the line (this code is already in file
1068 which is loaded if a document intended for
1076 If a PostScript procedure
1078 has been defined via a
1079 .RB \[oq] ps:\ def \[cq]
1081 .RB \[oq] ps:\ mdef \[cq]
1082 device command, it is executed at the beginning of every page (before
1083 anything is drawn or written by groff).
1085 For example, to underlay the page contents with the word
1086 \[oq]DRAFT\[cq] in light gray, you might use
1094 { gsave .9 setgray clippath pathbbox exch 2 copy
1095 .5 mul exch .5 mul translate atan rotate pop pop
1096 /NewCenturySchlbk-Roman findfont 200 scalefont setfont
1097 (DRAFT) dup stringwidth pop \-.5 mul \-70 moveto show
1106 Or, to cause lines and polygons to be drawn with square linecaps
1107 and mitered linejoins instead of the round linecaps and linejoins
1117 /BPhook { 2 setlinecap 0 setlinejoin } def
1124 (square linecaps, as opposed to butt linecaps (0 setlinecap),
1125 give true corners in boxed tables even though the lines are
1129 .\" ====================================================================
1130 .SS Encapsulated PostScript
1131 .\" ====================================================================
1134 itself doesn't emit bounding box information.
1136 With the help of Ghostscript the following simple script,
1138 produces an encapsulated PS file.
1146 groff \-P\-b16 $1 > $1.ps
1147 gs \-dNOPAUSE \-sDEVICE=bbox \-\- $1.ps 2> $1.bbox
1148 sed \-e "/\[ha]%%Orientation/r $1.bbox" \[rs]
1149 \-e "/\[ha]%!PS-Adobe-3.0/s/$/ EPSF-3.0/" $1.ps > $1.eps
1170 .\" ====================================================================
1171 .SS TrueType and other font formats
1172 .\" ====================================================================
1174 TrueType fonts can be used with
1176 if converted first to
1178 format, a special PostScript wrapper equivalent to the PFA format
1180 .BR \%pfbtops (@MAN1EXT@).
1182 There are several different methods to generate a type42 wrapper and
1183 most of them involve the use of a PostScript interpreter such as
1184 Ghostscript \[en] see
1189 Yet, the easiest method involves the use of the application
1194 (version 1.3.1) to generate type42
1195 font wrappers and well-formed AFM files that can be fed to
1197 .BR \%afmtodit (@MAN1EXT@)
1198 script to create appropriate metric files.
1200 The resulting font wrappers should be added to the
1204 source code can be downloaded from
1205 .UR ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/
1206 ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/
1211 Another solution for creating type42 wrappers is to use FontForge,
1213 .UR http://\:fontforge.sf.net
1214 http://\:fontforge.sf.net
1216 This font editor can convert most outline font formats.
1219 .\" ====================================================================
1220 .SH "FONT INSTALLATION"
1221 .\" ====================================================================
1223 This section gives a summary of the above explanations; it can serve
1224 as a step-by-step font installation guide for
1230 \h'-\w'\*[BU]'u'\*[BU]\c
1233 Convert your font to something groff understands.
1235 This is either a PostScript Type\~1 font in PFA format or a PostScript
1236 Type\~42 font, together with an AFM file.
1239 The very first characters in a PFA file look like this:
1243 .B %!PS-AdobeFont-1.0:
1247 A PFB file has this also in the first line, but the string is
1248 preceded with some binary bytes.
1251 The very first characters in a Type\~42 font file look like this:
1255 .B %!PS-TrueTypeFont
1259 This is a wrapper format for TrueType fonts.
1261 Old PS printers might not support it (this is, they don't have a
1262 built-in TrueType font interpreter).
1265 If your font is in PFB format (such fonts normally have
1267 as the file extension), you might use groff'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
1298 If you have a font family which comes with normal, bold, italic,
1299 and bold italic faces, it is recommended to use the letters
1305 respectively, as postfixes in the groff font names to make groff's
1306 \[oq].fam\[cq] request work.
1308 An example is groff's built-in Times-Roman font: The font family
1311 and the groff font names are
1319 Install both the groff font description files and the fonts in a
1321 subdirectory of the font path which groff finds.
1323 See section \[lq]Environment\[rq] in
1324 .BR troff (@MAN1EXT@)
1325 for the actual value of the font path.
1327 Note that groff doesn't use the AFM files (but it is a good idea
1328 to store them anyway).
1331 Register all fonts which must be downloaded to the printer in the
1335 Only the first occurrence of this file in the font path is read.
1337 This means that you should copy the default
1339 file to the first directory in your font path and add your fonts there.
1341 To continue the above example we assume that the PS font name for
1343 is \[oq]XY-Foo-Bar-Bold\[cq] (the PS font name is stored in the
1348 thus the following line should be added to
1353 .B XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
1358 .\" ====================================================================
1360 .\" ====================================================================
1362 groff versions 1.19.2 and earlier contain a slightly different set of
1363 the 35 Adobe core fonts; the difference is mainly the lack of the
1364 \[oq]Euro\[cq] glyph and a reduced set of kerning pairs.
1366 For backwards compatibility, these old fonts are installed also in the
1369 .I @OLDFONTDIR@/devps
1376 To use them, make sure that
1378 finds the fonts before the default system fonts (with the same names):
1379 Either add command-line option
1385 .B groff \-Tps \-P\-F \-P@OLDFONTDIR@ .\|.\|.
1388 or add the directory to groff's font path environment variable
1391 .B GROFF_FONT_PATH=@OLDFONTDIR@
1394 .\" ====================================================================
1396 .\" ====================================================================
1406 (in the font path) instead of the default prologue file
1411 overrides this environment variable.
1416 A list of directories in which to search for the
1418 directory in addition to the default ones.
1421 .BR @g@troff (@MAN1EXT@)
1423 .BR \%groff_font (@MAN5EXT@)
1428 .I SOURCE_DATE_EPOCH
1429 A timestamp (expressed as seconds since the Unix epoch) to use as the
1430 creation timestamp in place of the current time.
1433 .\" ====================================================================
1435 .\" ====================================================================
1438 .I @FONTDIR@/devps/DESC
1439 Device description file.
1442 .IR @FONTDIR@/devps/ F
1443 Font description file for font
1447 .I @FONTDIR@/devps/download
1448 List of downloadable fonts.
1451 .I @FONTDIR@/devps/text.enc
1452 Encoding used for text fonts.
1455 .I @MACRODIR@/ps.tmac
1458 automatically loaded by
1462 .I @MACRODIR@/pspic.tmac
1466 automatically loaded by
1470 .I @MACRODIR@/psold.tmac
1471 Macros to disable use of characters not present in older
1472 PostScript printers (e.g., \[oq]eth\[cq] or \[oq]thorn\[cq]).
1475 .IR /tmp/grops XXXXXX
1478 .BR groff (@MAN1EXT@)
1479 for details on the location of temporary files.
1482 .\" ====================================================================
1484 .\" ====================================================================
1486 .BR \%afmtodit (@MAN1EXT@),
1487 .BR groff (@MAN1EXT@),
1488 .BR @g@troff (@MAN1EXT@),
1489 .BR \%pfbtops (@MAN1EXT@),
1490 .BR \%groff_out (@MAN5EXT@),
1491 .BR \%groff_font (@MAN5EXT@),
1492 .BR \%groff_char (@MAN7EXT@),
1493 .BR \%groff_tmac (@MAN5EXT@)
1497 .UR http://\:partners.adobe.com/\:public/\:developer/\:en/\:ps/\:5001.DSC_Spec.pdf
1498 PostScript Language Document Structuring Conventions Specification
1502 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1506 .\" Local Variables:
1509 .\" vim: set filetype=groff:
projects / platform / upstream / groff.git / blob