2 Copyright (C) 1989-2000, 2001, 2002, 2003, 2004, 2005
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 will read 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.
133 Provide workarounds for older printers, broken spoolers, and previewers.
137 produces output at PostScript LanguageLevel\~2 that conforms to the
138 Document Structuring Conventions version 3.0.
140 Some older printers, spoolers, and previewers can't handle such output.
146 does to make its output acceptable to such programs.
148 A value of\~0 will cause grops not to employ any workarounds.
152 .B %%Begin\%Document\%Setup
154 .B %%End\%Document\%Setup
155 comments should be generated;
156 this is needed for early versions of TranScript that get confused by
159 comment and the first
164 Add\~2 if lines in included files beginning with
166 should be stripped out; this is needed for Sun's pageview previewer.
175 stripped out of included files; this is needed for spoolers that
183 Add\~8 if the first line of the PostScript output should be
187 this is needed when using Sun's Newsprint with a printer that requires
191 Add\~16 if no media size information should be included in the document
192 (this is, neither use
198 This was the behaviour of groff version 1.18.1 and earlier; it is needed
199 for older printers which don't understand PostScript LanguageLevel\~2.
201 It is also necessary if the output is further processed to get an
202 encapsulated PS (EPS) file -- see below.
205 The default value can be specified by a
212 command in the DESC file.
214 Otherwise the default value is\~0.
227 to the search path for prologue, font, and device description files;
229 is the name of the device, usually
234 Guess the page length.
236 This generates PostScript code that guesses the page length.
238 The guess will be correct only if the imageable area is vertically
239 centered on the page.
241 This option allows you to generate documents that can be printed
242 both on letter (8.5\(mu11) paper and on A4 paper without change.
246 This option may be used to specify a directory to search for
247 files on the command line and files named in
252 The current directory is always searched first.
253 This option may be specified more than once;
254 the directories will be searched in the order specified.
255 No directory search is performed for files specified using an absolute path.
259 Print the document in landscape format.
263 Turn manual feed on for the document.
267 Set physical dimension of output medium.
276 file; it accepts the same arguments as the
281 .B groff_font (@MAN5EXT@)
285 .BI \-P prologue-file
288 (in the font path) as the prologue instead of the default prologue file
291 This option overrides the environment variable
296 Lines should be drawn using a thickness of
298 thousandths of an em.
299 If this option is not given, the line thickness defaults to 0.04\~em.
303 Print the version number.
307 There are styles called
313 mounted at font positions 1 to\~4.
315 The fonts are grouped into families
325 having members in each of these styles:
337 AvantGarde-BookOblique
349 AvantGarde-DemiOblique
421 Helvetica-BoldOblique
433 Helvetica-Narrow-Oblique
439 Helvetica-Narrow-Bold
445 Helvetica-Narrow-BoldOblique
451 NewCenturySchlbk-Roman
457 NewCenturySchlbk-Italic
463 NewCenturySchlbk-Bold
469 NewCenturySchlbk-BoldItalic
522 There is also the following font which is not a member of a family:
528 ZapfChancery-MediumItalic
533 There are also some special fonts called
535 for the PS Symbol font, and
537 containing slanted lowercase Greek letters taken from PS Symbol.
539 Zapf Dingbats is available as
541 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
542 direction) is available as
544 most characters in these fonts are unnamed and must be accessed using
548 The default color for
552 is black; for colors defined in the `rgb' color space,
554 is used, for `cmy' and `cmyk'
560 is a PostScript LanguageLevel\~2 command and thus not available on some
565 understands various X\~commands produced using the
569 will only interpret commands that begin with a
574 .BI \[rs]X'ps:\ exec\ code '
575 This executes the arbitrary PostScript commands in
578 The PostScript currentpoint will be set to the position of the
580 command before executing
583 The origin will be at the top left corner of the page,
584 and y\~coordinates will increase down the page.
588 will be defined that converts groff units
589 to the coordinate system in effect.
599 \[rs]X'ps: exec \[rs]nx u 0 rlineto stroke'
604 will draw a horizontal line one inch long.
607 may make changes to the graphics state,
608 but any changes will persist only to the
611 A dictionary containing the definitions specified by the
615 will be on top of the dictionary stack.
617 If your code adds definitions to this dictionary,
618 you should allocate space for them using
619 .BI \[rs]X'ps\ mdef \ n '\fR.
621 Any definitions will persist only until the end of the page.
625 escape sequence with an argument that names a macro,
627 can extend over multiple lines.
638 \&\[rs]nx u 0 rlineto
646 is another way to draw a horizontal line one inch long.
650 .BI \[rs]X'ps:\ file\ name '
651 This is the same as the
653 command except that the PostScript code is read from file
657 .BI \[rs]X'ps:\ def\ code '
658 Place a PostScript definition contained in
662 There should be at most one definition per
666 Long definitions can be split over several
671 arguments are simply joined together separated by newlines.
673 The definitions are placed in a dictionary which is automatically
674 pushed on the dictionary stack when an
680 escape sequence with an argument that names a macro,
682 can extend over multiple lines.
685 .BI \[rs]X'ps:\ mdef\ n\ code '
695 needs to know how many definitions
698 so that it can create an appropriately sized PostScript dictionary
702 .BI \[rs]X'ps:\ import\ file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
703 Import a PostScript graphic from
712 give the bounding box of the graphic in the default PostScript
713 coordinate system; they should all be integers;
717 are the x and y\~coordinates of the lower left
718 corner of the graphic;
722 are the x and y\~coordinates of the upper right corner of the graphic;
726 are integers that give the desired width and height in groff
727 units of the graphic.
729 The graphic will be scaled so that it has this width and height
730 and translated so that the lower left corner of the graphic is
731 located at the position associated with
735 If the height argument is omitted it will be scaled uniformly in the
736 x and y\~directions so that it has the specified width.
738 Note that the contents of the
740 command are not interpreted by
742 so vertical space for the graphic is not automatically added,
747 arguments are not allowed to have attached scaling indicators.
749 If the PostScript file complies with the Adobe Document Structuring
750 Conventions and contains a
752 comment, then the bounding box can be automatically
753 extracted from within groff by using the
759 .BR groff_tmac (@MAN5EXT@)
760 for a description of the
762 macro which provides a convenient high-level interface for inclusion of
766 .B \[rs]X'ps:\ invis'
768 .B \[rs]X'ps:\ endinvis'
769 No output will be generated for text and drawing commands
770 that are bracketed with these
774 These commands are intended for use when output from
776 will be previewed before being processed with
778 if the previewer is unable to display certain characters
779 or other constructs, then other substitute characters or constructs
780 can be used for previewing by bracketing them with these
788 is not able to display a proper
790 character because the standard X11 fonts do not provide it;
791 this problem can be overcome by executing the following
797 \&.char \[rs](em \[rs]X'ps: invis'\[rs]
798 \[rs]Z'\[rs]v'-.25m'\[rs]h'.05m'\[rs]D'l .9m 0'\[rs]h'.05m''\[rs]
799 \[rs]X'ps: endinvis'\[rs](em
806 will be unable to display the
808 character and will draw the line,
814 and ignore the line (this code is already in file
816 which will be loaded if a document intended for
825 must be in the format output by
826 .BR @g@troff (@MAN1EXT@).
829 .BR groff_out (@MAN5EXT@).
832 In addition, the device and font description files for the device used
833 must meet certain requirements.
835 The device and font description files supplied for
837 device meet all these requirements.
839 .BR afmtodit (@MAN1EXT@)
840 can be used to create font files from AFM files.
842 The resolution must be an integer multiple of\~72 times the
847 device uses a resolution of 72000 and a sizescale of 1000.
850 The device description file must contain a valid paper size; see
851 .BR groff_font (@MAN5EXT@)
852 for more information.
855 Each font description file must contain a command
857 .BI internalname\ psname
859 which says that the PostScript name of the font is
862 It may also contain a command
864 .BI encoding\ enc_file
867 the PostScript font should be reencoded using the encoding described in
869 this file should consist of a sequence of lines of the form:
876 is the PostScript name of the character,
879 is its position in the encoding expressed as a decimal integer; valid
880 values are in the range 0 to\~255.
884 and blank lines are ignored.
886 The code for each character given in the font file must correspond
887 to the code for the character in encoding file, or to the code in the default
888 encoding for the font if the PostScript font is not to be reencoded.
890 This code can be used with the
894 to select the character,
895 even if the character does not have a groff name.
897 Every character in the font file must exist in the PostScript font, and
898 the widths given in the font file must match the widths used
899 in the PostScript font.
902 will assume that a character with a groff name of
904 is blank (makes no marks on the page);
905 it can make use of such a character to generate more efficient and
906 compact PostScript output.
911 is able to display all glyphs in a PostScript font, not only 256.
913 (or the default encoding if no encoding file specified) just defines the
914 order of glyphs for the first 256 characters; all other glyphs are
915 accessed with additional encoding vectors which
921 can automatically include the downloadable fonts necessary
922 to print the document.
923 Such fonts must be in PFA format.
925 .BR pfbtops (@MAN1EXT@)
926 to convert a Type\~1 font in PFB format.
927 Any downloadable fonts which should, when required, be included by
929 must be listed in the file
930 .BR @FONTDIR@/devps/download ;
931 this should consist of lines of the form
940 is the PostScript name of the font,
943 is the name of the file containing the font;
946 and blank lines are ignored;
947 fields may be separated by tabs or spaces;
949 will be searched for using the same mechanism that is used
950 for groff font metric files.
954 file itself will also be searched for using this mechanism;
955 currently, only the first found file in the font path is used.
958 If the file containing a downloadable font or imported document
959 conforms to the Adobe Document Structuring Conventions,
962 will interpret any comments in the files sufficiently to ensure that its
963 own output is conforming.
965 It will also supply any needed font resources that are listed in the
968 as well as any needed file resources.
970 It is also able to handle inter-resource dependencies.
972 For example, suppose that you have a downloadable font called Garamond,
973 and also a downloadable font called Garamond-Outline
974 which depends on Garamond
975 (typically it would be defined to copy Garamond's font dictionary,
976 and change the PaintType),
977 then it is necessary for Garamond to appear before Garamond-Outline
978 in the PostScript document.
981 will handle this automatically
982 provided that the downloadable font file for Garamond-Outline
983 indicates its dependence on Garamond by means of
984 the Document Structuring Conventions,
985 for example by beginning with the following lines
989 %!PS-Adobe-3.0 Resource-Font
992 %%DocumentNeededResources: font Garamond
998 %%IncludeResource: font Garamond
1001 In this case both Garamond and Garamond-Outline would need to be listed
1006 A downloadable font should not include its own name in a
1007 .B %%Document\%Supplied\%Resources
1013 .B %%Document\%Fonts
1017 .BR %%Document\%Needed\%Resources ,
1018 .BR %%Document\%Supplied\%Resources ,
1019 .BR %%Include\%Resource ,
1020 .BR %%Begin\%Resource ,
1024 (or possibly the old
1025 .BR %%Document\%Needed\%Fonts ,
1026 .BR %%Document\%Supplied\%Fonts ,
1027 .BR %%Include\%Font ,
1035 .SS Encapsulated PostScript
1037 itself doesn't emit bounding box information.
1039 With the help of GhostScript the following commands will produce an
1040 encapsulated PS file
1047 groff -P-b16 foo > foo.ps
1050 gs -dNOPAUSE -sDEVICE=bbox -- foo.ps 2> foo.bbox
1053 cat foo.ps | sed \-e '/%%Orientation/rfoo.bbx' > foo.eps
1062 TrueType fonts can be used with
1064 if converted first to
1066 format, an especial PostScript wrapper equivalent to the
1067 PFA format mentioned in
1068 .BR pfbtops (@MAN1EXT@).
1069 There are several different methods to generate a type42
1070 wrapper and most of them involve the use of a PostScript
1071 interpreter such as Ghostscript \(em see
1073 Yet, the easiest method involves the use of the application
1077 (version 1.3.1) to generate type42
1078 font wrappers and well-formed AFM files that can be fed to
1080 .BR afmtodit (@MAN1EXT@)
1081 script to create appropriate metric files.
1082 The resulting font wrappers should be added to the
1086 source code can be downloaded from
1087 .URL ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/ \
1088 ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/ .
1101 (in the font path) instead of the default prologue file
1106 overrides this environment variable.
1110 .Tp \w'\fB@FONTDIR@/devps/download'u+2n
1111 .B @FONTDIR@/devps/DESC
1112 Device description file.
1115 .BI @FONTDIR@/devps/ F
1116 Font description file for font
1120 .B @FONTDIR@/devps/download
1121 List of downloadable fonts.
1124 .B @FONTDIR@/devps/text.enc
1125 Encoding used for text fonts.
1128 .B @MACRODIR@/ps.tmac
1131 automatically loaded by
1135 .B @MACRODIR@/pspic.tmac
1139 automatically loaded by
1143 .B @MACRODIR@/psold.tmac
1144 Macros to disable use of characters not present in older
1145 PostScript printers (e.g. `eth' or `thorn').
1148 .BI /tmp/grops XXXXXX
1153 .BR afmtodit (@MAN1EXT@),
1154 .BR groff (@MAN1EXT@),
1155 .BR @g@troff (@MAN1EXT@),
1156 .BR pfbtops (@MAN1EXT@),
1157 .BR groff_out (@MAN5EXT@),
1158 .BR groff_font (@MAN5EXT@),
1159 .BR groff_char (@MAN7EXT@),
1160 .BR groff_tmac (@MAN5EXT@)
1163 .URL "http://\:partners.adobe.com/\:public/\:developer/\:en/\:ps/\:5001.DSC_Spec.pdf" \
1164 "PostScript Language Document Structuring Conventions Specification"
1168 .\" Local Variables: