2 Copyright (C) 1989-1995 Free Software Foundation, Inc.
4 Permission is granted to make and distribute verbatim copies of
5 this manual provided the copyright notice and this permission notice
6 are preserved on all copies.
8 Permission is granted to copy and distribute modified versions of this
9 manual under the conditions for verbatim copying, provided that the
10 entire resulting derived work is distributed under the terms of a
11 permission notice identical to this one.
13 Permission is granted to copy and distribute translations of this
14 manual into another language, under the above conditions for modified
15 versions, except that this permission notice may be included in
16 translations approved by the Free Software Foundation instead of in
19 .\" Like TP, but if specified indent is more than half
20 .\" the current line-length - indent, use the default indent.
22 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
25 .TH GROPS @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
27 grops \- PostScript driver for groff
45 translates the output of GNU
50 should be invoked by using the groff command
54 .if '@DEVICE@'ps' (Actually, this is the default for groff.)
55 If no files are given,
57 will read the standard input.
62 to read the standard input.
63 PostScript output is written to the standard output.
68 options can be passed to
77 Workaround broken spoolers and previewers.
80 produces output that conforms
81 the Document Structuring Conventions version 3.0.
82 Unfortunately some spoolers and previewers can't handle such output.
87 does to its output acceptable to such programs.
88 A value of 0 will cause grops not to employ any workarounds.
90 .B %%BeginDocumentSetup
93 comments should be generated;
94 this is needed for early versions of TranScript that get confused by
100 Add 2 if lines in included files beginning with
102 should be stripped out; this is needed for Sun's pageview previewer.
109 stripped out of included files; this is needed for spoolers that
115 Add 8 if the first line of the PostScript output should be
119 this is needed when using Sun's Newsprint with a printer that requires
121 The default value can be specified by a
126 command in the DESC file.
127 Otherwise the default value is 0.
136 Guess the page length.
137 This generates PostScript code that guesses the page length.
138 The guess will be correct only if the imageable area is vertically
139 centered on the page.
140 This option allows you to generate documents that can be printed
141 both on letter (8.5\(mu11) paper and on A4 paper without change.
144 Print the document in landscape format.
147 Turn manual feed on for the document.
152 for font and device description files;
154 is the name of the device, usually
158 Lines should be drawn using a thickness of
160 thousandths of an em.
163 Print the version number.
165 There are styles called
171 mounted at font positions 1 to 4.
172 The fonts are grouped into families
182 having members in each of these styles:
184 .if '\\*(.T'ps' .ft \\$1
194 AvantGarde-BookOblique
204 AvantGarde-DemiOblique
264 Helvetica-BoldOblique
274 Helvetica-Narrow-Oblique
279 Helvetica-Narrow-Bold
284 Helvetica-Narrow-BoldOblique
289 NewCenturySchlbk-Roman
294 NewCenturySchlbk-Italic
299 NewCenturySchlbk-Bold
304 NewCenturySchlbk-BoldItalic
347 There is also the following font which is not a member of a family:
351 ZapfChancery-MediumItalic
354 There are also some special fonts called
358 Zapf Dingbats is available as
360 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
361 direction) is available as
363 most characters in these fonts are unnamed and must be accessed using
367 understands various X commands produced using the
371 will only interpret commands that begin with a
375 .BI \eX'ps:\ exec\ code '
376 This executes the arbitrary PostScript commands in
378 The PostScript currentpoint will be set to the position of the
380 command before executing
382 The origin will be at the top left corner of the page,
383 and y coordinates will increase down the page.
386 will be defined that converts groff units
387 to the coordinate system in effect.
395 \eX'ps: exec \enx u 0 rlineto stroke'
399 will draw a horizontal line one inch long.
401 may make changes to the graphics state,
402 but any changes will persist only to the
404 A dictionary containing the definitions specified by the
408 will be on top of the dictionary stack.
409 If your code adds definitions to this dictionary,
410 you should allocate space for them using
411 .BI \eX'ps\ mdef \ n '\fR.
412 Any definitions will persist only until the end of the page.
415 escape sequence with an argument that names a macro,
417 can extend over multiple lines.
433 is another way to draw a horizontal line one inch long.
436 .BI \eX'ps:\ file\ name '
437 This is the same as the
439 command except that the PostScript code is read from file
442 .BI \eX'ps:\ def\ code '
443 Place a PostScript definition contained in
446 There should be at most one definition per
449 Long definitions can be split over several
454 arguments are simply joined together separated by newlines.
455 The definitions are placed in a dictionary which is automatically
456 pushed on the dictionary stack when an
461 escape sequence with an argument that names a macro,
463 can extend over multiple lines.
465 .BI \eX'ps:\ mdef\ n\ code '
474 needs to know how many definitions
477 so that it can create an appropriately sized PostScript dictionary
480 .BI \eX'ps:\ import\ file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
481 Import a PostScript graphic from
489 give the bounding box of the graphic in the default PostScript
490 coordinate system; they should all be integers;
494 are the x and y coordinates of the lower left
495 corner of the graphic;
499 are the x and y coordinates of the upper right corner of the graphic;
503 are integers that give the desired width and height in groff
504 units of the graphic.
505 The graphic will be scaled so that it has this width and height
506 and translated so that the lower left corner of the graphic is
507 located at the position associated with
510 If the height argument is omitted it will be scaled uniformly in the
511 x and y directions so that it has the specified width.
512 Note that the contents of the
514 command are not interpreted by
516 so vertical space for the graphic is not automatically added,
521 arguments are not allowed to have attached scaling indicators.
522 If the PostScript file complies with the Adobe Document Structuring
523 Conventions and contains a
525 comment, then the bounding box can be automatically
526 extracted from within groff by using the
535 macros (which are automatically loaded when
537 is run by the groff command) include a
539 macro which allows a picture to be easily imported.
542 \&\fB.PSPIC\fP [ \fB\-L\fP | \fB-R\fP | \fB\-I\fP \fIn\fP ]\ \"
543 \fI\|file\fP [ \fIwidth\fP [ \fIheight\fP ]]
546 is the name of the file containing the illustration;
550 give the desired width and height of the graphic.
555 arguments may have scaling indicators attached;
556 the default scaling indicator is
558 This macro will scale the graphic uniformly
559 in the x and y directions so that it is no more than
565 By default, the graphic will be horizontally centered.
570 cause the graphic to be left-aligned and right-aligned
574 option causes the graphic to be indented by
582 .B \eX'ps:\ endinvis'
583 No output will be generated for text and drawing commands
584 that are bracketed with these
587 These commands are intended for use when output from
589 will be previewed before being processed with
591 if the previewer is unable to display certain characters
592 or other constructs, then other substitute characters or constructs
593 can be used for previewing by bracketing them with these
600 is not able to display a proper
602 character because the standard X11 fonts do not provide it;
603 this problem can be overcome by executing the following
608 \&.char \e(em \eX'ps: invis'\e
609 \eZ'\ev'-.25m'\eh'.05m'\eD'l .9m 0'\eh'.05m''\e
610 \eX'ps: endinvis'\e(em
616 will be unable to display the
618 character and will draw the line,
629 must be in the format output by
630 .BR @g@troff (@MAN1EXT@).
632 .BR groff_out (@MAN5EXT@).
633 In addition the device and font description files for the device used
634 must meet certain requirements.
635 The device and font description files supplied for
637 device meet all these requirements.
638 .BR afmtodit (@MAN1EXT@)
639 can be used to create font files from AFM files.
640 The resolution must be an integer multiple of 72 times the
644 device uses a resolution of 72000 and a sizescale of 1000.
645 The device description file should contain a command
649 which says that output should be generated which is suitable for
650 printing on a page whose length is
653 Each font description file must contain a command
655 .BI internalname\ psname
657 which says that the PostScript name of the font is
659 It may also contain a command
661 .BI encoding\ enc_file
664 the PostScript font should be reencoded using the encoding described in
666 this file should consist of a sequence of lines of the form:
673 is the PostScript name of the character,
676 is its position in the encoding expressed as a decimal integer.
677 The code for each character given in the font file must correspond
678 to the code for the character in encoding file, or to the code in the default
679 encoding for the font if the PostScript font is not to be reencoded.
680 This code can be used with the
684 to select the character,
685 even if the character does not have a groff name.
686 Every character in the font file must exist in the PostScript font, and
687 the widths given in the font file must match the widths used
688 in the PostScript font.
690 will assume that a character with a groff name of
692 is blank (makes no marks on the page);
693 it can make use of such a character to generate more efficient and
694 compact PostScript output.
697 can automatically include the downloadable fonts necessary
698 to print the document.
699 Any downloadable fonts which should, when required, be included by
701 must be listed in the file
702 .BR @FONTDIR@/devps/download ;
703 this should consist of lines of the form
710 is the PostScript name of the font,
713 is the name of the file containing the font;
716 and blank lines are ignored;
717 fields may be separated by tabs or spaces;
719 will be searched for using the same mechanism that is used
720 for groff font metric files.
723 file itself will also be searched for using this mechanism.
725 If the file containing a downloadable font or imported document
726 conforms to the Adobe Document Structuring Conventions,
729 will interpret any comments in the files sufficiently to ensure that its
730 own output is conforming.
731 It will also supply any needed font resources that are listed in the
734 as well as any needed file resources.
735 It is also able to handle inter-resource dependencies.
736 For example, suppose that you have a downloadable font called Garamond,
737 and also a downloadable font called Garamond-Outline
738 which depends on Garamond
739 (typically it would be defined to copy Garamond's font dictionary,
740 and change the PaintType),
741 then it is necessary for Garamond to be appear before Garamond-Outline
742 in the PostScript document.
744 will handle this automatically
745 provided that the downloadable font file for Garamond-Outline
746 indicates its dependence on Garamond by means of
747 the Document Structuring Conventions,
748 for example by beginning with the following lines
751 %!PS-Adobe-3.0 Resource-Font
754 %%DocumentNeededResources: font Garamond
760 %%IncludeResource: font Garamond
762 In this case both Garamond and Garamond-Outline would need to be listed
766 A downloadable font should not include its own name in a
767 .B %%DocumentSuppliedResources
775 .BR %%DocumentNeededResources ,
776 .BR %%DocumentSuppliedResources ,
777 .BR %%IncludeResource ,
783 .BR %%DocumentNeededFonts ,
784 .BR %%DocumentSuppliedFonts ,
792 .Tp \w'\fB@FONTDIR@/devps/download'u+2n
793 .B @FONTDIR@/devps/DESC
794 Device description file.
796 .BI @FONTDIR@/devps/ F
797 Font description file for font
800 .B @FONTDIR@/devps/download
801 List of downloadable fonts.
803 .B @FONTDIR@/devps/text.enc
804 Encoding used for text fonts.
806 .B @MACRODIR@/tmac.ps
809 automatically loaded by
812 .B @MACRODIR@/tmac.pspic
816 automatically loaded by
819 .B @MACRODIR@/tmac.psold
820 Macros to disable use of characters not present in older
821 PostScript printers; automatically loaded by
824 .B @MACRODIR@/tmac.psnew
825 Macros to undo the effect of
828 .BI /tmp/grops XXXXXX
831 .\" .BR afmtodit (@MAN1EXT@),
832 .BR groff (@MAN1EXT@),
833 .BR @g@troff (@MAN1EXT@),
834 .BR psbb (@MAN1EXT@),
835 .BR groff_out (@MAN5EXT@),
836 .BR groff_font (@MAN5EXT@),
837 .BR groff_char (@MAN7EXT@)