| blob | da422b4c25764d720f29a29382999194c125b102 |
1 .ig \"-*- nroff -*-
2 Copyright (C) 1989-2000 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
17 the original English.
18 ..
19 .\" Like TP, but if specified indent is more than half
20 .\" the current line-length - indent, use the default indent.
21 .de Tp
22 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
23 .el .TP "\\$1"
24 ..
25 .TH GROPS @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
26 .SH NAME
27 grops \- PostScript driver for groff
28 .SH SYNOPSIS
29 .nr a \n(.j
30 .ad l
31 .nr i \n(.i
32 .in +\w'\fBgrops 'u
33 .ti \niu
34 .B grops
35 .de OP
36 .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
37 .el .RB "[\ " "\\$1" "\ ]"
38 ..
39 .OP \-glmv
40 .OP \-b n
41 .OP \-c n
42 .OP \-w n
43 .OP \-F dir
44 .RI "[\ " files\|.\|.\|. "\ ]"
45 .br
46 .ad \na
47 .PP
48 It is possible to have whitespace between a command line option and its
49 parameter.
50 .SH DESCRIPTION
51 .B grops
52 translates the output of GNU
53 .B troff
54 to PostScript.
55 Normally
56 .B grops
57 should be invoked by using the groff command
58 with a
59 .B \-Tps
60 option.
61 .if '@DEVICE@'ps' (Actually, this is the default for groff.)
62 If no files are given,
63 .B grops
64 will read the standard input.
65 A filename of
66 .B \-
67 will also cause
68 .B grops
69 to read the standard input.
70 PostScript output is written to the standard output.
71 When
72 .B grops
73 is run by
74 .B groff
75 options can be passed to
76 .B grops
77 using the
78 .B groff
79 .B \-P
80 option.
81 .SH OPTIONS
82 .TP
83 .BI \-b n
84 Workaround broken spoolers and previewers.
85 Normally
86 .B grops
87 produces output that conforms
88 the Document Structuring Conventions version 3.0.
89 Unfortunately some spoolers and previewers can't handle such output.
90 The value of
91 .I n
92 controls what
93 .B grops
94 does to its output acceptable to such programs.
95 A value of 0 will cause grops not to employ any workarounds.
96 Add 1 if no
97 .B %%BeginDocumentSetup
98 and
99 .B %%EndDocumentSetup
100 comments should be generated;
101 this is needed for early versions of TranScript that get confused by
102 anything between the
103 .B %%EndProlog
104 comment and the first
105 .B %%Page
106 comment.
107 Add 2 if lines in included files beginning with
108 .B %!
109 should be stripped out; this is needed for Sun's pageview previewer.
110 Add 4 if
111 .BR %%Page ,
112 .BR %%Trailer
113 and
114 .B %%EndProlog
115 comments should be
116 stripped out of included files; this is needed for spoolers that
117 don't understand the
118 .B %%BeginDocument
119 and
120 .B %%EndDocument
121 comments.
122 Add 8 if the first line of the PostScript output should be
123 .B %!PS-Adobe-2.0
124 rather than
125 .BR %!PS-Adobe-3.0 ;
126 this is needed when using Sun's Newsprint with a printer that requires
127 page reversal.
128 The default value can be specified by a
129 .RS
130 .IP
131 .BI broken\ n
132 .LP
133 command in the DESC file.
134 Otherwise the default value is 0.
135 .RE
136 .TP
137 .BI \-c n
138 Print
139 .I n
140 copies of each page.
141 .TP
142 .BI \-g
143 Guess the page length.
144 This generates PostScript code that guesses the page length.
145 The guess will be correct only if the imageable area is vertically
146 centered on the page.
147 This option allows you to generate documents that can be printed
148 both on letter (8.5\(mu11) paper and on A4 paper without change.
149 .TP
150 .B \-l
151 Print the document in landscape format.
152 .TP
153 .B \-m
154 Turn manual feed on for the document.
155 .TP
156 .BI \-F dir
157 Search the directory
158 .IB dir /dev name
159 for font and device description files;
160 .I name
161 is the name of the device, usually
162 .BR ps .
163 .TP
164 .BI \-w n
165 Lines should be drawn using a thickness of
166 .I n
167 thousandths of an em.
168 .TP
169 .B \-v
170 Print the version number.
171 .SH USAGE
172 There are styles called
173 .BR R ,
174 .BR I ,
175 .BR B ,
176 and
177 .B BI
178 mounted at font positions 1 to 4.
179 The fonts are grouped into families
180 .BR A ,
181 .BR BM ,
182 .BR C ,
183 .BR H ,
184 .BR HN ,
185 .BR N ,
186 .B P
187 and
188 .B T
189 having members in each of these styles:
190 .de FT
191 .if '\\*(.T'ps' .ft \\$1
192 ..
193 .TP
194 .B AR
195 .FT AR
196 AvantGarde-Book
197 .FT
198 .TP
199 .B AI
200 .FT AI
201 AvantGarde-BookOblique
202 .FT
203 .TP
204 .B AB
205 .FT AB
206 AvantGarde-Demi
207 .FT
208 .TP
209 .B ABI
210 .FT ABI
211 AvantGarde-DemiOblique
212 .FT
213 .TP
214 .B BMR
215 .FT BMR
216 Bookman-Light
217 .FT
218 .TP
219 .B BMI
220 .FT BMI
221 Bookman-LightItalic
222 .FT
223 .TP
224 .B BMB
225 .FT BMB
226 Bookman-Demi
227 .FT
228 .TP
229 .B BMBI
230 .FT BMBI
231 Bookman-DemiItalic
232 .FT
233 .TP
234 .B CR
235 .FT CR
236 Courier
237 .FT
238 .TP
239 .B CI
240 .FT CI
241 Courier-Oblique
242 .FT
243 .TP
244 .B CB
245 .FT CB
246 Courier-Bold
247 .FT
248 .TP
249 .B CBI
250 .FT CBI
251 Courier-BoldOblique
252 .FT
253 .TP
254 .B HR
255 .FT HR
256 Helvetica
257 .FT
258 .TP
259 .B HI
260 .FT HI
261 Helvetica-Oblique
262 .FT
263 .TP
264 .B HB
265 .FT HB
266 Helvetica-Bold
267 .FT
268 .TP
269 .B HBI
270 .FT HBI
271 Helvetica-BoldOblique
272 .FT
273 .TP
274 .B HNR
275 .FT HNR
276 Helvetica-Narrow
277 .FT
278 .TP
279 .B HNI
280 .FT HNI
281 Helvetica-Narrow-Oblique
282 .FT
283 .TP
284 .B HNB
285 .FT HNB
286 Helvetica-Narrow-Bold
287 .FT
288 .TP
289 .B HNBI
290 .FT HNBI
291 Helvetica-Narrow-BoldOblique
292 .FT
293 .TP
294 .B NR
295 .FT NR
296 NewCenturySchlbk-Roman
297 .FT
298 .TP
299 .B NI
300 .FT NI
301 NewCenturySchlbk-Italic
302 .FT
303 .TP
304 .B NB
305 .FT NB
306 NewCenturySchlbk-Bold
307 .FT
308 .TP
309 .B NBI
310 .FT NBI
311 NewCenturySchlbk-BoldItalic
312 .FT
313 .TP
314 .B PR
315 .FT PR
316 Palatino-Roman
317 .FT
318 .TP
319 .B PI
320 .FT PI
321 Palatino-Italic
322 .FT
323 .TP
324 .B PB
325 .FT PB
326 Palatino-Bold
327 .FT
328 .TP
329 .B PBI
330 .FT PBI
331 Palatino-BoldItalic
332 .FT
333 .TP
334 .B TR
335 .FT TR
336 Times-Roman
337 .FT
338 .TP
339 .B TI
340 .FT TI
341 Times-Italic
342 .FT
343 .TP
344 .B TB
345 .FT TB
346 Times-Bold
347 .FT
348 .TP
349 .B TBI
350 .FT TBI
351 Times-BoldItalic
352 .FT
353 .LP
354 There is also the following font which is not a member of a family:
355 .TP
356 .B ZCMI
357 .FT ZCMI
358 ZapfChancery-MediumItalic
359 .FT
360 .LP
361 There are also some special fonts called
362 .B SS
363 and
364 .BR S .
365 Zapf Dingbats is available as
366 .BR ZD
367 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
368 direction) is available as
369 .BR ZDR ;
370 most characters in these fonts are unnamed and must be accessed using
371 .BR \eN .
372 .LP
373 .B grops
374 understands various X commands produced using the
375 .B \eX
376 escape sequence;
377 .B grops
378 will only interpret commands that begin with a
379 .B ps:
380 tag.
381 .TP
382 .BI \eX'ps:\ exec\ code '
383 This executes the arbitrary PostScript commands in
384 .IR code .
385 The PostScript currentpoint will be set to the position of the
386 .B \eX
387 command before executing
388 .IR code .
389 The origin will be at the top left corner of the page,
390 and y coordinates will increase down the page.
391 A procedure
392 .B u
393 will be defined that converts groff units
394 to the coordinate system in effect.
395 For example,
396 .RS
397 .IP
398 .B
399 \&.nr x 1i
400 .br
401 .B
402 \eX'ps: exec \enx u 0 rlineto stroke'
403 .br
404 .RE
405 .IP
406 will draw a horizontal line one inch long.
407 .I code
408 may make changes to the graphics state,
409 but any changes will persist only to the
410 end of the page.
411 A dictionary containing the definitions specified by the
412 .B def
413 and
414 .B mdef
415 will be on top of the dictionary stack.
416 If your code adds definitions to this dictionary,
417 you should allocate space for them using
418 .BI \eX'ps\ mdef \ n '\fR.
419 Any definitions will persist only until the end of the page.
420 If you use the
421 .B \eY
422 escape sequence with an argument that names a macro,
423 .I code
424 can extend over multiple lines.
425 For example,
426 .RS
427 .IP
428 .nf
429 .ft B
430 \&.nr x 1i
431 \&.de y
432 \&ps: exec
433 \&\enx u 0 rlineto
434 \&stroke
435 \&..
436 \&\eYy
437 .fi
438 .ft R
439 .LP
440 is another way to draw a horizontal line one inch long.
441 .RE
442 .TP
443 .BI \eX'ps:\ file\ name '
444 This is the same as the
445 .B exec
446 command except that the PostScript code is read from file
447 .IR name .
448 .TP
449 .BI \eX'ps:\ def\ code '
450 Place a PostScript definition contained in
451 .I code
452 in the prologue.
453 There should be at most one definition per
454 .B \eX
455 command.
456 Long definitions can be split over several
457 .B \eX
458 commands;
459 all the
460 .I code
461 arguments are simply joined together separated by newlines.
462 The definitions are placed in a dictionary which is automatically
463 pushed on the dictionary stack when an
464 .B exec
465 command is executed.
466 If you use the
467 .B \eY
468 escape sequence with an argument that names a macro,
469 .I code
470 can extend over multiple lines.
471 .TP
472 .BI \eX'ps:\ mdef\ n\ code '
473 Like
474 .BR def ,
475 except that
476 .I code
477 may contain up to
478 .I n
479 definitions.
480 .B grops
481 needs to know how many definitions
482 .I code
483 contains
484 so that it can create an appropriately sized PostScript dictionary
485 to contain them.
486 .TP
487 .BI \eX'ps:\ import\ file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
488 Import a PostScript graphic from
489 .IR file .
490 The arguments
491 .IR llx ,
492 .IR lly ,
493 .IR urx ,
494 and
495 .I ury
496 give the bounding box of the graphic in the default PostScript
497 coordinate system; they should all be integers;
498 .I llx
499 and
500 .I lly
501 are the x and y coordinates of the lower left
502 corner of the graphic;
503 .I urx
504 and
505 .I ury
506 are the x and y coordinates of the upper right corner of the graphic;
507 .I width
508 and
509 .I height
510 are integers that give the desired width and height in groff
511 units of the graphic.
512 The graphic will be scaled so that it has this width and height
513 and translated so that the lower left corner of the graphic is
514 located at the position associated with
515 .B \eX
516 command.
517 If the height argument is omitted it will be scaled uniformly in the
518 x and y directions so that it has the specified width.
519 Note that the contents of the
520 .B \eX
521 command are not interpreted by
522 .BR troff ;
523 so vertical space for the graphic is not automatically added,
524 and the
525 .I width
526 and
527 .I height
528 arguments are not allowed to have attached scaling indicators.
529 If the PostScript file complies with the Adobe Document Structuring
530 Conventions and contains a
531 .B %%BoundingBox
532 comment, then the bounding box can be automatically
533 extracted from within groff by using the
534 .B psbb
535 request.
536 .RS
537 .LP
538 The
539 .B \-mps
540 macros (which are automatically loaded when
541 .B grops
542 is run by the groff command) include a
543 .B PSPIC
544 macro which allows a picture to be easily imported.
545 This has the format
546 .IP
547 \&\fB.PSPIC\fP [ \fB\-L\fP | \fB-R\fP | \fB\-I\fP \fIn\fP ]\ \"
548 \fI\|file\fP [ \fIwidth\fP [ \fIheight\fP ]]
549 .LP
550 .I file
551 is the name of the file containing the illustration;
552 .I width
553 and
554 .I height
555 give the desired width and height of the graphic.
556 The
557 .I width
558 and
559 .I height
560 arguments may have scaling indicators attached;
561 the default scaling indicator is
562 .BR i .
563 This macro will scale the graphic uniformly
564 in the x and y directions so that it is no more than
565 .I width
566 wide
567 and
568 .I height
569 high.
570 By default, the graphic will be horizontally centered.
571 The
572 .BI \-L
573 and
574 .BI \-R
575 cause the graphic to be left-aligned and right-aligned
576 respectively.
577 The
578 .B \-I
579 option causes the graphic to be indented by
580 .IR n .
581 .RE
582 .TP
583 .B \eX'ps:\ invis'
584 .br
585 .ns
586 .TP
587 .B \eX'ps:\ endinvis'
588 No output will be generated for text and drawing commands
589 that are bracketed with these
590 .B \eX
591 commands.
592 These commands are intended for use when output from
593 .B troff
594 will be previewed before being processed with
595 .BR grops ;
596 if the previewer is unable to display certain characters
597 or other constructs, then other substitute characters or constructs
598 can be used for previewing by bracketing them with these
599 .B \eX
600 commands.
601 .RS
602 .LP
603 For example,
604 .B gxditview
605 is not able to display a proper
606 .B \e(em
607 character because the standard X11 fonts do not provide it;
608 this problem can be overcome by executing the following
609 request
610 .IP
611 .ft B
612 .nf
613 \&.char \e(em \eX'ps: invis'\e
614 \eZ'\ev'-.25m'\eh'.05m'\eD'l .9m 0'\eh'.05m''\e
615 \eX'ps: endinvis'\e(em
616 .ft
617 .fi
618 .LP
619 In this case,
620 .B gxditview
621 will be unable to display the
622 .B \e(em
623 character and will draw the line,
624 whereas
625 .B grops
626 will print the
627 .B \e(em
628 character
629 and ignore the line.
630 .RE
631 .LP
632 The input to
633 .B grops
634 must be in the format output by
635 .BR @g@troff (@MAN1EXT@).
636 This is described in
637 .BR groff_out (@MAN1EXT@).
638 In addition the device and font description files for the device used
639 must meet certain requirements.
640 The device and font description files supplied for
641 .B ps
642 device meet all these requirements.
643 .BR afmtodit (@MAN1EXT@)
644 can be used to create font files from AFM files.
645 The resolution must be an integer multiple of 72 times the
646 .BR sizescale .
647 The
648 .B ps
649 device uses a resolution of 72000 and a sizescale of 1000.
650 The device description file should contain a command
651 .IP
652 .BI paperlength\ n
653 .LP
654 which says that output should be generated which is suitable for
655 printing on a page whose length is
656 .I n
657 machine units.
658 Each font description file must contain a command
659 .IP
660 .BI internalname\ psname
661 .LP
662 which says that the PostScript name of the font is
663 .IR psname .
664 It may also contain a command
665 .IP
666 .BI encoding\ enc_file
667 .LP
668 which says that
669 the PostScript font should be reencoded using the encoding described in
670 .IR enc_file ;
671 this file should consist of a sequence of lines of the form:
672 .IP
673 .I
674 pschar code
675 .LP
676 where
677 .I pschar
678 is the PostScript name of the character,
679 and
680 .I code
681 is its position in the encoding expressed as a decimal integer.
682 The code for each character given in the font file must correspond
683 to the code for the character in encoding file, or to the code in the default
684 encoding for the font if the PostScript font is not to be reencoded.
685 This code can be used with the
686 .B \eN
687 escape sequence in
688 .B troff
689 to select the character,
690 even if the character does not have a groff name.
691 Every character in the font file must exist in the PostScript font, and
692 the widths given in the font file must match the widths used
693 in the PostScript font.
694 .B grops
695 will assume that a character with a groff name of
696 .B space
697 is blank (makes no marks on the page);
698 it can make use of such a character to generate more efficient and
699 compact PostScript output.
700 .LP
701 .B grops
702 can automatically include the downloadable fonts necessary
703 to print the document.
704 Any downloadable fonts which should, when required, be included by
705 .B grops
706 must be listed in the file
707 .BR @FONTDIR@/devps/download ;
708 this should consist of lines of the form
709 .IP
710 .I
711 font filename
712 .LP
713 where
714 .I font
715 is the PostScript name of the font,
716 and
717 .I filename
718 is the name of the file containing the font;
719 lines beginning with
720 .B #
721 and blank lines are ignored;
722 fields may be separated by tabs or spaces;
723 .I filename
724 will be searched for using the same mechanism that is used
725 for groff font metric files.
726 The
727 .B download
728 file itself will also be searched for using this mechanism.
729 .LP
730 If the file containing a downloadable font or imported document
731 conforms to the Adobe Document Structuring Conventions,
732 then
733 .B grops
734 will interpret any comments in the files sufficiently to ensure that its
735 own output is conforming.
736 It will also supply any needed font resources that are listed in the
737 .B download
738 file
739 as well as any needed file resources.
740 It is also able to handle inter-resource dependencies.
741 For example, suppose that you have a downloadable font called Garamond,
742 and also a downloadable font called Garamond-Outline
743 which depends on Garamond
744 (typically it would be defined to copy Garamond's font dictionary,
745 and change the PaintType),
746 then it is necessary for Garamond to be appear before Garamond-Outline
747 in the PostScript document.
748 .B grops
749 will handle this automatically
750 provided that the downloadable font file for Garamond-Outline
751 indicates its dependence on Garamond by means of
752 the Document Structuring Conventions,
753 for example by beginning with the following lines
754 .IP
755 .B
756 %!PS-Adobe-3.0 Resource-Font
757 .br
758 .B
759 %%DocumentNeededResources: font Garamond
760 .br
761 .B
762 %%EndComments
763 .br
764 .B
765 %%IncludeResource: font Garamond
766 .LP
767 In this case both Garamond and Garamond-Outline would need to be listed
768 in the
769 .B download
770 file.
771 A downloadable font should not include its own name in a
772 .B %%DocumentSuppliedResources
773 comment.
774 .LP
775 .B grops
776 will not interpret
777 .B %%DocumentFonts
778 comments.
779 The
780 .BR %%DocumentNeededResources ,
781 .BR %%DocumentSuppliedResources ,
782 .BR %%IncludeResource ,
783 .BR %%BeginResource
784 and
785 .BR %%EndResource
786 comments
787 (or possibly the old
788 .BR %%DocumentNeededFonts ,
789 .BR %%DocumentSuppliedFonts ,
790 .BR %%IncludeFont ,
791 .BR %%BeginFont
792 and
793 .BR %%EndFont
794 comments)
795 should be used.
796 .SH FILES
797 .Tp \w'\fB@FONTDIR@/devps/download'u+2n
798 .B @FONTDIR@/devps/DESC
799 Device description file.
800 .TP
801 .BI @FONTDIR@/devps/ F
802 Font description file for font
803 .IR F .
804 .TP
805 .B @FONTDIR@/devps/download
806 List of downloadable fonts.
807 .TP
808 .B @FONTDIR@/devps/text.enc
809 Encoding used for text fonts.
810 .TP
811 .B @MACRODIR@/tmac.ps
812 Macros for use with
813 .BR grops ;
814 automatically loaded by
815 .BR troffrc
816 .TP
817 .B @MACRODIR@/tmac.pspic
818 Definition of
819 .B PSPIC
820 macro,
821 automatically loaded by
822 .BR tmac.ps .
823 .TP
824 .B @MACRODIR@/tmac.psold
825 Macros to disable use of characters not present in older
826 PostScript printers; automatically loaded by
827 .BR tmac.ps .
828 .TP
829 .B @MACRODIR@/tmac.psnew
830 Macros to undo the effect of
831 .BR tmac.psold .
832 .TP
833 .BI /tmp/grops XXXXXX
834 Temporary file.
835 .SH "SEE ALSO"
836 .BR afmtodit (@MAN1EXT@),
837 .BR groff (@MAN1EXT@),
838 .BR @g@troff (@MAN1EXT@),
839 .BR psbb (@MAN1EXT@),
840 .BR groff_out (@MAN5EXT@),
841 .BR groff_font (@MAN5EXT@),
842 .BR groff_char (@MAN7EXT@)