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