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