contrib/groff/grops/grops.man

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