4 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
6 Copyright (C) 1989 - 2006, 2008
7 Free Software Foundation, Inc.
9 Permission is granted to make and distribute verbatim copies of
10 this manual provided the copyright notice and this permission notice
11 are preserved on all copies.
13 Permission is granted to copy and distribute modified versions of this
14 manual under the conditions for verbatim copying, provided that the
15 entire resulting derived work is distributed under the terms of a
16 permission notice identical to this one.
18 Permission is granted to copy and distribute translations of this
19 manual into another language, under the above conditions for modified
20 versions, except that this permission notice may be included in
21 translations approved by the Free Software Foundation instead of in
25 .do nr __compat \n[.C]
28 .\" Like TP, but if specified indent is more than half
29 .\" the current line-length - indent, use the default indent.
31 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
36 . ie '\\*(.T'ps' .ft \\$1
37 . el .if '\\*(.T'pdf' .ft \\$1
40 .TH @U_D_PS@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
45 @L_D_PS@ \- PostScript driver for @T_ROFF@
64 It is possible to have whitespace between a command line option and its
71 translates the output of
75 It should normally be invoked by using the @L_ROFF@ command
80 .if '@DEVICE@'ps' (Actually, this is the default for @T_ROFF@.)
82 If no files are given, the standard input is read.
86 also causes reading of the standard input.
88 PostScript output is written to the standard output.
94 options can be passed to
104 doesn't produce a valid document structure (conforming to the Document
105 Structuring Convention) if called with multiple file arguments.
107 To print such concatenated output it is necessary to deactivate DSC
108 handling in the printing program or previewer.
112 below for a guide how to install fonts for use with
120 Provide workarounds for older printers, broken spoolers, and previewers.
122 Normally output at PostScript LanguageLevel\~2 is produced that conforms
123 to the Document Structuring Conventions version 3.0.
125 Some older printers, spoolers, and previewers can't handle such output.
131 does to make its output acceptable to such programs.
133 A value of\~0 causes @L_D_PS@ not to employ any workarounds.
137 .B %%Begin\%Document\%Setup
139 .B %%End\%Document\%Setup
140 comments should be generated;
141 this is needed for early versions of TranScript that get confused by
144 comment and the first
149 Add\~2 if lines in included files beginning with
151 should be stripped out; this is needed for Sun's pageview previewer.
160 stripped out of included files; this is needed for spoolers that
168 Add\~8 if the first line of the PostScript output should be
172 this is needed when using Sun's Newsprint with a printer that requires
176 Add\~16 if no media size information should be included in the document
177 (this is, neither use
183 This behaviour is needed for older printers which don't understand PostScript
186 It is also necessary if the output is further processed to get an
187 encapsulated PS (EPS) file \[en] see below.
190 The default value can be specified by a
197 command in the DESC file.
199 Otherwise the default value is\~0.
212 to the search path for prologue, font, and device description files;
214 is the name of the device, usually
219 Guess the page length.
221 This generates PostScript code that guesses the page length.
223 The guess is correct only if the imageable area is vertically
224 centered on the page.
226 This option allows you to generate documents that can be printed
227 both on letter (8.5\[mu]11) paper and on A4 paper without change.
231 This option may be used to add a directory to the search path for
232 files on the command line and files named in
233 .B \[rs]X'ps: import'
238 The search path is initialized with the current directory.
240 This option may be specified more than once; the directories are then
241 searched in the order specified (but before the current directory).
243 If you want to make the current directory be read before other directories,
246 at the appropriate place.
249 No directory search is performed for files with an absolute file name.
253 Print the document in landscape format.
257 Turn manual feed on for the document.
261 Set physical dimension of output medium.
270 file; it accepts the same arguments as the
275 .B @L_ROFF@-font (@MAN5EXT@)
279 .BI \-P prologue-file
282 (in the font path) as the prologue instead of the default prologue file
285 This option overrides the environment variable
286 .SM @U_D_PS@_PROLOGUE.
290 Lines should be drawn using a thickness of
292 thousandths of an em.
294 If this option is not given, the line thickness defaults to 0.04\~em.
298 Print the version number.
305 must be in the format output by
306 .BR @L_TROFF@ (@MAN1EXT@).
309 .BR @L_ROFF@-out (@MAN5EXT@).
312 In addition, the device and font description files for the device used
313 must meet certain requirements:
315 The resolution must be an integer multiple of\~72 times the
320 device uses a resolution of 72000 and a sizescale of 1000.
323 The device description file must contain a valid paper size; see
324 .BR @L_ROFF@-font (@MAN5EXT@)
325 for more information.
328 Each font description file must contain a command
330 .BI internalname\ psname
332 which says that the PostScript name of the font is
335 It may also contain a command
337 .BI encoding\ enc_file
340 the PostScript font should be reencoded using the encoding described in
342 this file should consist of a sequence of lines of the form:
349 is the PostScript name of the character,
352 is its position in the encoding expressed as a decimal integer; valid
353 values are in the range 0 to\~255.
357 and blank lines are ignored.
359 The code for each character given in the font file must correspond
360 to the code for the character in encoding file, or to the code in the default
361 encoding for the font if the PostScript font is not to be reencoded.
363 This code can be used with the
367 to select the character,
368 even if the character does not have a @T_ROFF@ name.
370 Every character in the font file must exist in the PostScript font, and
371 the widths given in the font file must match the widths used
372 in the PostScript font.
375 assumes that a character with a @T_ROFF@ name of
377 is blank (makes no marks on the page);
378 it can make use of such a character to generate more efficient and
379 compact PostScript output.
384 is able to display all glyphs in a PostScript font, not only 256.
386 (or the default encoding if no encoding file specified) just defines the
387 order of glyphs for the first 256 characters; all other glyphs are
388 accessed with additional encoding vectors which are produced on the fly.
391 can automatically include the
392 Downloadable fonts necessary to print the document are automatically
395 Such fonts must be in PFA format.
398 .BR \%@L_PFBTOPS@ (@MAN1EXT@)
399 to convert a Type\~1 font in PFB format.
401 Any downloadable fonts which should, when required, be included by
403 must be listed in the file
404 .BR @FONTDIR@/ps/download ;
405 this should consist of lines of the form
414 is the PostScript name of the font,
417 is the name of the file containing the font;
420 and blank lines are ignored;
421 fields may be separated by tabs or spaces;
423 is searched for using the same mechanism that is used
424 for @T_ROFF@ font metric files.
428 file itself is also searched for using this mechanism;
429 currently, only the first found file in the font path is used.
432 If the file containing a downloadable font or imported document
433 conforms to the Adobe Document Structuring Conventions,
436 interprets any comments in the files sufficiently to ensure that its
437 own output is conforming.
439 It also supplies any needed font resources that are listed in the
442 as well as any needed file resources.
444 It is also able to handle inter-resource dependencies.
446 For example, suppose that you have a downloadable font called Garamond,
447 and also a downloadable font called Garamond-Outline
448 which depends on Garamond
449 (typically it would be defined to copy Garamond's font dictionary,
450 and change the PaintType),
451 then it is necessary for Garamond to appear before Garamond-Outline
452 in the PostScript document.
454 This is automatically handled
455 provided that the downloadable font file for Garamond-Outline
456 indicates its dependence on Garamond by means of
457 the Document Structuring Conventions,
458 for example by beginning with the following lines
462 %!PS-Adobe-3.0 Resource-Font
465 %%DocumentNeededResources: font Garamond
471 %%IncludeResource: Font Garamond
474 In this case both Garamond and Garamond-Outline would need to be listed
479 A downloadable font should not include its own name in a
480 .B %%Document\%Supplied\%Resources
485 comments are not interpreted.
488 .BR %%Document\%Needed\%Resources ,
489 .BR %%Document\%Supplied\%Resources ,
490 .BR %%Include\%Resource ,
491 .BR %%Begin\%Resource ,
496 .BR %%Document\%Needed\%Fonts ,
497 .BR %%Document\%Supplied\%Fonts ,
498 .BR %%Include\%Font ,
507 there are styles called
513 mounted at font positions 1 to\~4.
515 The fonts are grouped into families
525 having members in each of these styles:
537 AvantGarde-BookOblique
549 AvantGarde-DemiOblique
621 Helvetica-BoldOblique
633 Helvetica-Narrow-Oblique
639 Helvetica-Narrow-Bold
645 Helvetica-Narrow-BoldOblique
651 NewCenturySchlbk-Roman
657 NewCenturySchlbk-Italic
663 NewCenturySchlbk-Bold
669 NewCenturySchlbk-BoldItalic
722 There is also the following font which is not a member of a family:
728 ZapfChancery-MediumItalic
733 There are also some special fonts called
735 for the PS Symbol font, and
737 containing slanted lowercase Greek letters taken from PS Symbol.
739 Zapf Dingbats is available as
741 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
742 direction) is available as
744 most characters in these fonts are unnamed and must be accessed using
748 The default color for
752 is black; for colors defined in the `rgb' color space
754 is used, for `cmy' and `cmyk'
761 is a PostScript LanguageLevel\~2 command and thus not available on some
765 Various X\~commands produced using the
767 escape sequence are understood, of which only commands that begin with a
772 .BI \[rs]X'ps:\ exec\ code '
773 This executes the arbitrary PostScript commands in
776 The PostScript currentpoint is set to the position of the
778 command before executing
781 The origin is at the top left corner of the page,
782 and y\~coordinates increase down the page.
786 is defined that converts @T_ROFF@ units
787 to the coordinate system in effect (provided the user doesn't change the
798 \[rs]X'ps: exec \[rs]nx u 0 rlineto stroke'
803 draws a horizontal line one inch long.
806 may make changes to the graphics state,
807 but any changes persist only to the end of the page.
809 A dictionary containing the definitions specified by the
813 is on top of the dictionary stack.
815 If your code adds definitions to this dictionary,
816 you should allocate space for them using
817 .BI \[rs]X'ps\ mdef \ n '\fR.
819 Any definitions persist only until the end of the page.
823 escape sequence with an argument that names a macro,
825 can extend over multiple lines.
836 \&\[rs]nx u 0 rlineto
844 is another way to draw a horizontal line one inch long.
846 Note the single backslash before `nx' \[en] the only reason to use a number
847 register while defining the macro `y' is to convert a user-specified
848 dimension `1i' to internal @T_ROFF@ units which are in turn converted to PS
855 wraps user-specified PostScript code into a dictionary, nothing more.
857 In particular, it doesn't start and end the inserted code with
863 This must be supplied by the user, if necessary.
868 .BI \[rs]X'ps:\ file\ name '
869 This is the same as the
871 command except that the PostScript code is read from file
875 .BI \[rs]X'ps:\ def\ code '
876 Place a PostScript definition contained in
880 There should be at most one definition per
884 Long definitions can be split over several
889 arguments are simply joined together separated by newlines.
891 The definitions are placed in a dictionary which is automatically
892 pushed on the dictionary stack when an
898 escape sequence with an argument that names a macro,
900 can extend over multiple lines.
903 .BI \[rs]X'ps:\ mdef\ n\ code '
913 needs to know how many definitions
916 so that it can create an appropriately sized PostScript dictionary
920 .BI \[rs]X'ps:\ import\ file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
921 Import a PostScript graphic from
930 give the bounding box of the graphic in the default PostScript
931 coordinate system; they should all be integers;
935 are the x and y\~coordinates of the lower left
936 corner of the graphic;
940 are the x and y\~coordinates of the upper right corner of the graphic;
944 are integers that give the desired width and height in @T_ROFF@
945 units of the graphic.
948 The graphic is scaled so that it has this width and height
949 and translated so that the lower left corner of the graphic is
950 located at the position associated with
954 If the height argument is omitted it is scaled uniformly in the
955 x and y\~directions so that it has the specified width.
958 Note that the contents of the
960 command are not interpreted by
962 so vertical space for the graphic is not automatically added,
967 arguments are not allowed to have attached scaling indicators.
970 If the PostScript file complies with the Adobe Document Structuring
971 Conventions and contains a
973 comment, then the bounding box can be automatically
974 extracted from within @T_ROFF@ by using the
980 .BR @L_ROFF@-tmac (@MAN5EXT@)
981 for a description of the
983 macro which provides a convenient high-level interface for inclusion of
987 .B \[rs]X'ps:\ invis'
989 .B \[rs]X'ps:\ endinvis'
990 No output is generated for text and drawing commands
991 that are bracketed with these
995 These commands are intended for use when output from
997 is previewed before being processed with
999 if the previewer is unable to display certain characters
1000 or other constructs, then other substitute characters or constructs
1001 can be used for previewing by bracketing them with these
1008 If a PostScript procedure
1010 has been defined via a
1014 device command, it is executed at the beginning
1015 of every page (before anything is drawn or written).
1016 For example, to underlay the page contents with the word
1017 `DRAFT' in light gray, you might use
1025 { gsave .9 setgray clippath pathbbox exch 2 copy
1026 .5 mul exch .5 mul translate atan rotate pop pop
1027 /NewCenturySchlbk-Roman findfont 200 scalefont setfont
1028 (DRAFT) dup stringwidth pop \-.5 mul \-70 moveto show
1037 Or, to cause lines and polygons to be drawn with square linecaps
1038 and mitered linejoins instead of the round linecaps and linejoins
1048 /BPhook { 2 setlinecap 0 setlinejoin } def
1055 (square linecaps, as opposed to butt linecaps (0 setlinecap),
1056 give true corners in boxed tables even though the lines are
1060 .SS Encapsulated PostScript
1062 itself doesn't emit bounding box information.
1064 With the help of Ghostscript the following simple script,
1066 produces an encapsulated PS file.
1073 @L_ROFF@ \-P\-b16 "${1} > "${1}.ps"
1074 trap "rm -f \e"${1}.ps\e"; exit" 0 1 2 15
1075 gs \-dNOPAUSE \-sDEVICE=bbox \-\- "${1}.ps" 2> "${1}.bbox"
1076 trap "rm -f \e"${1}.ps\e" \e"${1}.bbox\e"; exit" 0 1 2 15
1077 < "${1}.ps" sed \-e "/\[ha]%%Orientation/r ${1}.bbox" \[rs]
1078 \-e '/\[ha]%!PS-Adobe-3.0/s/$/ EPSF-3.0/' > "${1}.eps"
1097 .SS TrueType and other font formats
1098 TrueType fonts can be used with
1100 if converted first to
1102 format, a special PostScript wrapper equivalent to the
1103 PFA format mentioned in
1104 .BR \%@L_PFBTOPS@ (@MAN1EXT@).
1106 There are several different methods to generate a type42
1107 wrapper and most of them involve the use of a PostScript
1108 interpreter such as Ghostscript \[en] see
1112 Yet, the easiest method involves the use of the application
1117 (version 1.3.1) to generate type42
1118 font wrappers and well-formed AFM files that can be fed to
1120 .BR \%@L_AFMTODIT@ (@MAN1EXT@)
1121 script to create appropriate metric files.
1123 The resulting font wrappers should be added to the
1127 source code can be downloaded from
1128 .UR ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/
1129 ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/
1133 Another solution for creating type42 wrappers is to use FontForge,
1135 .UR http://\:fontforge.sf.net
1136 http://\:fontforge.sf.net
1138 This font editor can convert most outline font formats.
1141 .SH FONT INSTALLATION
1143 This section gives a summary of the above explanations; it can serve
1144 as a step-by-step font installation guide.
1149 \h'-\w'\*[BU]'u'\*[BU]\c
1152 Convert your font to something @T_ROFF@ understands.
1154 This is either a PostScript Type\~1 font in PFA format or a
1155 PostScript Type\~42 font, together with an AFM file.
1158 The very first characters in a PFA file look like this:
1162 .B %!PS-AdobeFont-1.0:
1166 A PFB file has this also in the first line, but the string is
1167 preceded with some binary bytes.
1170 The very first characters in a Type\~42 font file look like this:
1174 .B %!PS-TrueTypeFont
1178 This is a wrapper format for TrueType fonts.
1180 Old PS printers might not support it (this is, they don't have a
1181 built-in TrueType font interpreter).
1184 If your font is in PFB format (such fonts normally have `.pfb' as
1185 the file extension), you might use
1186 .BR \%@L_PFBTOPS@ (@MAN1EXT@)
1187 program to convert it to PFA.
1189 For TrueType fonts, try
1193 For all other font formats use
1195 which can convert most outline font formats.
1198 Convert the AFM file to a font description file with the
1199 .BR \%@L_AFMTODIT@ (@MAN1EXT@)
1206 @L_AFMTODIT@ Foo-Bar-Bold.afm textmap FBB
1210 which converts the metric file `Foo-Bar-Bold.afm' to the @T_ROFF@
1213 If you have a font family which comes with normal, bold, italic,
1214 and bold italic faces, it is recommended to use the letters
1220 respectively, as postfixes in the @T_ROFF@ font names to make the
1221 `.fam' request work.
1223 An example is the built-in Times-Roman font: The font family name
1226 and the font names are
1234 Install both the font description files and the fonts in a
1235 `devps' subdirectory of the font path which @T_ROFF@ can find.
1240 .BR @L_TROFF@ (@MAN1EXT@)
1241 man page which lists the actual value of the font path.
1243 Note that @T_ROFF@ doesn't use the AFM files (but it is a good idea to
1247 Register all fonts which must be downloaded to the printer in the
1248 `devps/download' file.
1250 Only the first occurrence of this file in the font path is read.
1252 This means that you should copy the default `download' file to the
1253 first directory in your font path and add your fonts there.
1255 To continue the above example we assume that the PS font name for
1256 Foo-Bar-Bold.pfa is `XY-Foo-Bar-Bold' (the PS font name is stored in the
1258 field in the `FBB' file), thus the following line should be added to
1263 .B XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
1272 .B @U_D_PS@_PROLOGUE
1279 (in the font path) instead of the default prologue file
1284 overrides this environment variable.
1289 .B @U_ROFF@_FONT_PATH
1290 A list of directories in which to search for the
1292 directory in addition to the default ones.
1295 .BR @L_TROFF@ (@MAN1EXT@)
1297 .BR \%@L_ROFF@-font (@MAN5EXT@)
1303 .Tp \w'\fB@FONTDIR@/ps/download'u+2n
1304 .B @FONTDIR@/ps/DESC
1305 Device description file.
1309 Font description file for font
1313 .B @FONTDIR@/ps/download
1314 List of downloadable fonts.
1317 .B @FONTDIR@/ps/text.enc
1318 Encoding used for text fonts.
1321 .B @MACRODIR@/ps.tmac
1324 automatically loaded by
1328 .B @MACRODIR@/pspic.tmac
1332 automatically loaded by
1336 .B @MACRODIR@/psold.tmac
1337 Macros to disable use of characters not present in older
1338 PostScript printers (e.g., `eth' or `thorn').
1343 .BR \%@L_AFMTODIT@ (@MAN1EXT@),
1344 .BR @L_ROFF@ (@MAN1EXT@),
1345 .BR @L_TROFF@ (@MAN1EXT@),
1346 .BR \%@L_PFBTOPS@ (@MAN1EXT@),
1347 .BR \%@L_ROFF@-out (@MAN5EXT@),
1348 .BR \%@L_ROFF@-font (@MAN5EXT@),
1349 .BR \%@L_ROFF@-char (@MAN7EXT@),
1350 .BR \%@L_ROFF@-tmac (@MAN5EXT@)
1353 .UR http://\:partners.adobe.com/\:public/\:developer/\:en/\:ps/\:5001.DSC_Spec.pdf
1354 PostScript Language Document Structuring Conventions Specification