contrib/groff-1.19/src/devices/grops/grops.man

   1 .ig
   2 Copyright (C) 1989-2000, 2001, 2002, 2003, 2004, 2005
   3   Free Software Foundation, Inc.
   4
   5 Permission is granted to make and distribute verbatim copies of
   6 this manual provided the copyright notice and this permission notice
   7 are preserved on all copies.
   8
   9 Permission is granted to copy and distribute modified versions of this
  10 manual under the conditions for verbatim copying, provided that the
  11 entire resulting derived work is distributed under the terms of a
  12 permission notice identical to this one.
  13
  14 Permission is granted to copy and distribute translations of this
  15 manual into another language, under the above conditions for modified
  16 versions, except that this permission notice may be included in
  17 translations approved by the Free Software Foundation instead of in
  18 the original English.
  19 ..
  20 .
  21 .do nr grops_C \n[.C]
  22 .cp 0
  23 .
  24 .mso www.tmac
  25 .
  26 .
  27 .\" Like TP, but if specified indent is more than half
  28 .\" the current line-length - indent, use the default indent.
  29 .de Tp
  30 .  ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
  31 .  el .TP "\\$1"
  32 ..
  33 .
  34 .de TQ
  35 .  br
  36 .  ns
  37 .  TP \$1
  38 ..
  39 .
  40 .de FT
  41 .  if '\\*(.T'ps' .ft \\$1
  42 ..
  43 .
  44 .
  45 .TH GROPS @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
  46 .
  47 .
  48 .SH NAME
  49 grops \- PostScript driver for groff
  50 .
  51 .
  52 .SH SYNOPSIS
  53 .nr a \n(.j
  54 .ad l
  55 .nr i \n(.i
  56 .in +\w'\fBgrops 'u
  57 .ti \niu
  58 .B grops
  59 .
  60 .de OP
  61 .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\%\\$2" "\ ]"
  62 .el .RB "[\ " "\\$1" "\ ]"
  63 ..
  64 .
  65 .OP \-glmv
  66 .OP \-b n
  67 .OP \-c n
  68 .OP \-F dir
  69 .OP \-I dir
  70 .OP \-p papersize
  71 .OP \-P prologue
  72 .OP \-w n
  73 .RI "[\ " files\|.\|.\|. "\ ]"
  74 .br
  75 .ad \na
  76 .
  77 .PP
  78 It is possible to have whitespace between a command line option and its
  79 parameter.
  80 .
  81 .
  82 .SH DESCRIPTION
  83 .B grops
  84 translates the output of GNU
  85 .B troff
  86 to PostScript.
  87 .
  88 Normally
  89 .B grops
  90 should be invoked by using the groff command
  91 with a
  92 .B \-Tps
  93 option.
  94 .
  95 .if '@DEVICE@'ps' (Actually, this is the default for groff.)
  96 .
  97 If no files are given,
  98 .B grops
  99 will read the standard input.
 100 .
 101 A filename of
 102 .B \-
 103 will also cause
 104 .B grops
 105 to read the standard input.
 106 .
 107 PostScript output is written to the standard output.
 108 .
 109 When
 110 .B grops
 111 is run by
 112 .B groff
 113 options can be passed to
 114 .B grops
 115 using the
 116 .B groff
 117 .B \-P
 118 option.
 119 .
 120 .PP
 121 Note that
 122 .B grops
 123 doesn't produce a valid document structure (conforming to the Document
 124 Structuring Convention) if called with multiple file arguments.
 125 .
 126 To print such concatenated output it is necessary to deactivate DSC
 127 handling in the printing program or previewer.
 128 .
 129 .
 130 .SH OPTIONS
 131 .TP
 132 .BI \-b n
 133 Provide workarounds for older printers, broken spoolers, and previewers.
 134 .
 135 Normally
 136 .B grops
 137 produces output at PostScript LanguageLevel\~2 that conforms to the
 138 Document Structuring Conventions version 3.0.
 139 .
 140 Some older printers, spoolers, and previewers can't handle such output.
 141 .
 142 The value of\~\c
 143 .I n
 144 controls what
 145 .B grops
 146 does to make its output acceptable to such programs.
 147 .
 148 A value of\~0 will cause grops not to employ any workarounds.
 149 .
 150 .IP
 151 Add\~1 if no
 152 .B %%Begin\%Document\%Setup
 153 and
 154 .B %%End\%Document\%Setup
 155 comments should be generated;
 156 this is needed for early versions of TranScript that get confused by
 157 anything between the
 158 .B %%End\%Prolog
 159 comment and the first
 160 .B %%Page
 161 comment.
 162 .
 163 .IP
 164 Add\~2 if lines in included files beginning with
 165 .B %!
 166 should be stripped out; this is needed for Sun's pageview previewer.
 167 .
 168 .IP
 169 Add\~4 if
 170 .BR %%Page ,
 171 .BR %%Trailer
 172 and
 173 .B %%End\%Prolog
 174 comments should be
 175 stripped out of included files; this is needed for spoolers that
 176 don't understand the
 177 .B %%Begin\%Document
 178 and
 179 .B %%End\%Document
 180 comments.
 181 .
 182 .IP
 183 Add\~8 if the first line of the PostScript output should be
 184 .B %!PS-Adobe-2.0
 185 rather than
 186 .BR %!PS-Adobe-3.0 ;
 187 this is needed when using Sun's Newsprint with a printer that requires
 188 page reversal.
 189 .
 190 .IP
 191 Add\~16 if no media size information should be included in the document
 192 (this is, neither use
 193 .B %%Document\%Media
 194 nor the
 195 .B setpagedevice
 196 PostScript command).
 197 .
 198 This was the behaviour of groff version 1.18.1 and earlier; it is needed
 199 for older printers which don't understand PostScript LanguageLevel\~2.
 200 .
 201 It is also necessary if the output is further processed to get an
 202 encapsulated PS (EPS) file -- see below.
 203 .
 204 .IP
 205 The default value can be specified by a
 206 .
 207 .RS
 208 .IP
 209 .BI broken\  n
 210 .
 211 .LP
 212 command in the DESC file.
 213 .
 214 Otherwise the default value is\~0.
 215 .RE
 216 .
 217 .TP
 218 .BI \-c n
 219 Print
 220 .I n
 221 copies of each page.
 222 .
 223 .TP
 224 .BI \-F dir
 225 Prepend directory
 226 .IB dir /dev name
 227 to the search path for prologue, font, and device description files;
 228 .I name
 229 is the name of the device, usually
 230 .BR ps .
 231 .
 232 .TP
 233 .BI \-g
 234 Guess the page length.
 235 .
 236 This generates PostScript code that guesses the page length.
 237 .
 238 The guess will be correct only if the imageable area is vertically
 239 centered on the page.
 240 .
 241 This option allows you to generate documents that can be printed
 242 both on letter (8.5\(mu11) paper and on A4 paper without change.
 243 .
 244 .TP
 245 .BI \-I dir
 246 This option may be used to specify a directory to search for
 247 files on the command line and files named in
 248 .B \eX'ps: import'
 249 and
 250 .B \eX'ps: file'
 251 escapes.
 252 The current directory is always searched first.
 253 This option may be specified more than once;
 254 the directories will be searched in the order specified.
 255 No directory search is performed for files specified using an absolute path.
 256 .
 257 .TP
 258 .B \-l
 259 Print the document in landscape format.
 260 .
 261 .TP
 262 .B \-m
 263 Turn manual feed on for the document.
 264 .
 265 .TP
 266 .BI \-p paper-size
 267 Set physical dimension of output medium.
 268 .
 269 This overrides the
 270 .BR papersize ,
 271 .BR paperlength ,
 272 and
 273 .B paperwidth
 274 commands in the
 275 .B DESC
 276 file; it accepts the same arguments as the
 277 .B papersize
 278 command.
 279 .
 280 See
 281 .B groff_font (@MAN5EXT@)
 282 for details.
 283 .
 284 .TP
 285 .BI \-P prologue-file
 286 Use the file
 287 .I prologue-file
 288 (in the font path) as the prologue instead of the default prologue file
 289 .BR prologue .
 290 .
 291 This option overrides the environment variable
 292 .SM GROPS_PROLOGUE.
 293 .
 294 .TP
 295 .BI \-w n
 296 Lines should be drawn using a thickness of
 297 .IR n \~\c
 298 thousandths of an em.
 299 If this option is not given, the line thickness defaults to 0.04\~em.
 300 .
 301 .TP
 302 .B \-v
 303 Print the version number.
 304 .
 305 .
 306 .SH USAGE
 307 There are styles called
 308 .BR R ,
 309 .BR I ,
 310 .BR B ,
 311 and
 312 .B BI
 313 mounted at font positions 1 to\~4.
 314 .
 315 The fonts are grouped into families
 316 .BR A ,
 317 .BR BM ,
 318 .BR C ,
 319 .BR H ,
 320 .BR HN ,
 321 .BR N ,
 322 .BR P ,
 323 and\~\c
 324 .B T
 325 having members in each of these styles:
 326 .
 327 .RS
 328 .TP
 329 .B AR
 330 .FT AR
 331 AvantGarde-Book
 332 .FT
 333 .
 334 .TQ
 335 .B AI
 336 .FT AI
 337 AvantGarde-BookOblique
 338 .FT
 339 .
 340 .TQ
 341 .B AB
 342 .FT AB
 343 AvantGarde-Demi
 344 .FT
 345 .
 346 .TQ
 347 .B ABI
 348 .FT ABI
 349 AvantGarde-DemiOblique
 350 .FT
 351 .
 352 .TQ
 353 .B BMR
 354 .FT BMR
 355 Bookman-Light
 356 .FT
 357 .
 358 .TQ
 359 .B BMI
 360 .FT BMI
 361 Bookman-LightItalic
 362 .FT
 363 .
 364 .TQ
 365 .B BMB
 366 .FT BMB
 367 Bookman-Demi
 368 .FT
 369 .
 370 .TQ
 371 .B BMBI
 372 .FT BMBI
 373 Bookman-DemiItalic
 374 .FT
 375 .
 376 .TQ
 377 .B CR
 378 .FT CR
 379 Courier
 380 .FT
 381 .
 382 .TQ
 383 .B CI
 384 .FT CI
 385 Courier-Oblique
 386 .FT
 387 .
 388 .TQ
 389 .B CB
 390 .FT CB
 391 Courier-Bold
 392 .FT
 393 .
 394 .TQ
 395 .B CBI
 396 .FT CBI
 397 Courier-BoldOblique
 398 .FT
 399 .
 400 .TQ
 401 .B HR
 402 .FT HR
 403 Helvetica
 404 .FT
 405 .
 406 .TQ
 407 .B HI
 408 .FT HI
 409 Helvetica-Oblique
 410 .FT
 411 .
 412 .TQ
 413 .B HB
 414 .FT HB
 415 Helvetica-Bold
 416 .FT
 417 .
 418 .TQ
 419 .B HBI
 420 .FT HBI
 421 Helvetica-BoldOblique
 422 .FT
 423 .
 424 .TQ
 425 .B HNR
 426 .FT HNR
 427 Helvetica-Narrow
 428 .FT
 429 .
 430 .TQ
 431 .B HNI
 432 .FT HNI
 433 Helvetica-Narrow-Oblique
 434 .FT
 435 .
 436 .TQ
 437 .B HNB
 438 .FT HNB
 439 Helvetica-Narrow-Bold
 440 .FT
 441 .
 442 .TQ
 443 .B HNBI
 444 .FT HNBI
 445 Helvetica-Narrow-BoldOblique
 446 .FT
 447 .
 448 .TQ
 449 .B NR
 450 .FT NR
 451 NewCenturySchlbk-Roman
 452 .FT
 453 .
 454 .TQ
 455 .B NI
 456 .FT NI
 457 NewCenturySchlbk-Italic
 458 .FT
 459 .
 460 .TQ
 461 .B NB
 462 .FT NB
 463 NewCenturySchlbk-Bold
 464 .FT
 465 .
 466 .TQ
 467 .B NBI
 468 .FT NBI
 469 NewCenturySchlbk-BoldItalic
 470 .FT
 471 .
 472 .TQ
 473 .B PR
 474 .FT PR
 475 Palatino-Roman
 476 .FT
 477 .
 478 .TQ
 479 .B PI
 480 .FT PI
 481 Palatino-Italic
 482 .FT
 483 .
 484 .TQ
 485 .B PB
 486 .FT PB
 487 Palatino-Bold
 488 .FT
 489 .
 490 .TQ
 491 .B PBI
 492 .FT PBI
 493 Palatino-BoldItalic
 494 .FT
 495 .
 496 .TQ
 497 .B TR
 498 .FT TR
 499 Times-Roman
 500 .FT
 501 .
 502 .TQ
 503 .B TI
 504 .FT TI
 505 Times-Italic
 506 .FT
 507 .
 508 .TQ
 509 .B TB
 510 .FT TB
 511 Times-Bold
 512 .FT
 513 .
 514 .TQ
 515 .B TBI
 516 .FT TBI
 517 Times-BoldItalic
 518 .FT
 519 .RE
 520 .
 521 .LP
 522 There is also the following font which is not a member of a family:
 523 .
 524 .RS
 525 .TP
 526 .B ZCMI
 527 .FT ZCMI
 528 ZapfChancery-MediumItalic
 529 .FT
 530 .RE
 531 .
 532 .LP
 533 There are also some special fonts called
 534 .B S
 535 for the PS Symbol font, and
 536 .BR SS ,
 537 containing slanted lowercase Greek letters taken from PS Symbol.
 538 .
 539 Zapf Dingbats is available as
 540 .BR ZD
 541 and a reversed version of ZapfDingbats (with symbols pointing in the opposite
 542 direction) is available as
 543 .BR ZDR ;
 544 most characters in these fonts are unnamed and must be accessed using
 545 .BR \[rs]N .
 546 .
 547 .LP
 548 The default color for
 549 .B \[rs]m
 550 and
 551 .B \[rs]M
 552 is black; for colors defined in the `rgb' color space,
 553 .B setrgbcolor
 554 is used, for `cmy' and `cmyk'
 555 .BR setcmykcolor ,
 556 and for `gray'
 557 .BR setgray .
 558 Note that
 559 .B setcmykcolor
 560 is a PostScript LanguageLevel\~2 command and thus not available on some
 561 older printers.
 562 .
 563 .LP
 564 .B grops
 565 understands various X\~commands produced using the
 566 .B \[rs]X
 567 escape sequence;
 568 .B grops
 569 will only interpret commands that begin with a
 570 .B ps:
 571 tag.
 572 .
 573 .TP
 574 .BI \[rs]X'ps:\ exec\  code '
 575 This executes the arbitrary PostScript commands in
 576 .IR code .
 577 .
 578 The PostScript currentpoint will be set to the position of the
 579 .B \[rs]X
 580 command before executing
 581 .IR code .
 582 .
 583 The origin will be at the top left corner of the page,
 584 and y\~coordinates will increase down the page.
 585 .
 586 A procedure\~\c
 587 .B u
 588 will be defined that converts groff units
 589 to the coordinate system in effect.
 590 .
 591 For example,
 592 .
 593 .RS
 594 .IP
 595 .B
 596 \&.nr x 1i
 597 .br
 598 .B
 599 \[rs]X'ps: exec \[rs]nx u 0 rlineto stroke'
 600 .br
 601 .RE
 602 .
 603 .IP
 604 will draw a horizontal line one inch long.
 605 .
 606 .I code
 607 may make changes to the graphics state,
 608 but any changes will persist only to the
 609 end of the page.
 610 .
 611 A dictionary containing the definitions specified by the
 612 .B def
 613 and
 614 .B mdef
 615 will be on top of the dictionary stack.
 616 .
 617 If your code adds definitions to this dictionary,
 618 you should allocate space for them using
 619 .BI \[rs]X'ps\ mdef \ n '\fR.
 620 .
 621 Any definitions will persist only until the end of the page.
 622 .
 623 If you use the
 624 .B \[rs]Y
 625 escape sequence with an argument that names a macro,
 626 .I code
 627 can extend over multiple lines.
 628 .
 629 For example,
 630 .
 631 .RS
 632 .IP
 633 .nf
 634 .ft B
 635 \&.nr x 1i
 636 \&.de y
 637 \&ps: exec
 638 \&\[rs]nx u 0 rlineto
 639 \&stroke
 640 \&..
 641 \&\[rs]Yy
 642 .fi
 643 .ft R
 644 .
 645 .LP
 646 is another way to draw a horizontal line one inch long.
 647 .RE
 648 .
 649 .TP
 650 .BI \[rs]X'ps:\ file\  name '
 651 This is the same as the
 652 .B exec
 653 command except that the PostScript code is read from file
 654 .IR name .
 655 .
 656 .TP
 657 .BI \[rs]X'ps:\ def\  code '
 658 Place a PostScript definition contained in
 659 .I code
 660 in the prologue.
 661 .
 662 There should be at most one definition per
 663 .B \[rs]X
 664 command.
 665 .
 666 Long definitions can be split over several
 667 .B \[rs]X
 668 commands;
 669 all the
 670 .I code
 671 arguments are simply joined together separated by newlines.
 672 .
 673 The definitions are placed in a dictionary which is automatically
 674 pushed on the dictionary stack when an
 675 .B exec
 676 command is executed.
 677 .
 678 If you use the
 679 .B \[rs]Y
 680 escape sequence with an argument that names a macro,
 681 .I code
 682 can extend over multiple lines.
 683 .
 684 .TP
 685 .BI \[rs]X'ps:\ mdef\  n\ code  '
 686 Like
 687 .BR def ,
 688 except that
 689 .I code
 690 may contain up to
 691 .IR n \~\c
 692 definitions.
 693 .
 694 .B grops
 695 needs to know how many definitions
 696 .I code
 697 contains
 698 so that it can create an appropriately sized PostScript dictionary
 699 to contain them.
 700 .
 701 .TP
 702 .BI \[rs]X'ps:\ import\  file\ llx\ lly\ urx\ ury\ width\ \fR[\fP\ height\ \fR]\fP '
 703 Import a PostScript graphic from
 704 .IR file .
 705 .
 706 The arguments
 707 .IR llx ,
 708 .IR lly ,
 709 .IR urx ,
 710 and
 711 .I ury
 712 give the bounding box of the graphic in the default PostScript
 713 coordinate system; they should all be integers;
 714 .I llx
 715 and
 716 .I lly
 717 are the x and y\~coordinates of the lower left
 718 corner of the graphic;
 719 .I urx
 720 and
 721 .I ury
 722 are the x and y\~coordinates of the upper right corner of the graphic;
 723 .I width
 724 and
 725 .I height
 726 are integers that give the desired width and height in groff
 727 units of the graphic.
 728 .
 729 The graphic will be scaled so that it has this width and height
 730 and translated so that the lower left corner of the graphic is
 731 located at the position associated with
 732 .B \[rs]X
 733 command.
 734 .
 735 If the height argument is omitted it will be scaled uniformly in the
 736 x and y\~directions so that it has the specified width.
 737 .
 738 Note that the contents of the
 739 .B \[rs]X
 740 command are not interpreted by
 741 .BR troff ;
 742 so vertical space for the graphic is not automatically added,
 743 and the
 744 .I width
 745 and
 746 .I height
 747 arguments are not allowed to have attached scaling indicators.
 748 .
 749 If the PostScript file complies with the Adobe Document Structuring
 750 Conventions and contains a
 751 .B %%Bounding\%Box
 752 comment, then the bounding box can be automatically
 753 extracted from within groff by using the
 754 .B psbb
 755 request.
 756 .
 757 .IP
 758 See
 759 .BR groff_tmac (@MAN5EXT@)
 760 for a description of the
 761 .B PSPIC
 762 macro which provides a convenient high-level interface for inclusion of
 763 PostScript graphics.
 764 .
 765 .TP
 766 .B \[rs]X'ps:\ invis'
 767 .TQ
 768 .B \[rs]X'ps:\ endinvis'
 769 No output will be generated for text and drawing commands
 770 that are bracketed with these
 771 .B \[rs]X
 772 commands.
 773 .
 774 These commands are intended for use when output from
 775 .B troff
 776 will be previewed before being processed with
 777 .BR grops ;
 778 if the previewer is unable to display certain characters
 779 or other constructs, then other substitute characters or constructs
 780 can be used for previewing by bracketing them with these
 781 .B \[rs]X
 782 commands.
 783 .
 784 .RS
 785 .LP
 786 For example,
 787 .B \%gxditview
 788 is not able to display a proper
 789 .B \[rs](em
 790 character because the standard X11 fonts do not provide it;
 791 this problem can be overcome by executing the following
 792 request
 793 .
 794 .IP
 795 .ft B
 796 .nf
 797 \&.char \[rs](em \[rs]X'ps: invis'\[rs]
 798 \[rs]Z'\[rs]v'-.25m'\[rs]h'.05m'\[rs]D'l .9m 0'\[rs]h'.05m''\[rs]
 799 \[rs]X'ps: endinvis'\[rs](em
 800 .ft
 801 .fi
 802 .
 803 .LP
 804 In this case,
 805 .B \%gxditview
 806 will be unable to display the
 807 .B \[rs](em
 808 character and will draw the line,
 809 whereas
 810 .B grops
 811 will print the
 812 .B \[rs](em
 813 character
 814 and ignore the line (this code is already in file
 815 .B Xps.tmac
 816 which will be loaded if a document intended for
 817 .B grops
 818 is previewed with
 819 .BR \%gxditview ).
 820 .RE
 821 .
 822 .LP
 823 The input to
 824 .B grops
 825 must be in the format output by
 826 .BR @g@troff (@MAN1EXT@).
 827 .
 828 This is described in
 829 .BR groff_out (@MAN5EXT@).
 830 .
 831 .LP
 832 In addition, the device and font description files for the device used
 833 must meet certain requirements.
 834 .
 835 The device and font description files supplied for
 836 .B ps
 837 device meet all these requirements.
 838 .
 839 .BR afmtodit (@MAN1EXT@)
 840 can be used to create font files from AFM files.
 841 .
 842 The resolution must be an integer multiple of\~72 times the
 843 .BR sizescale .
 844 .
 845 The
 846 .B ps
 847 device uses a resolution of 72000 and a sizescale of 1000.
 848 .
 849 .LP
 850 The device description file must contain a valid paper size; see
 851 .BR groff_font (@MAN5EXT@)
 852 for more information.
 853 .
 854 .LP
 855 Each font description file must contain a command
 856 .IP
 857 .BI internalname\  psname
 858 .LP
 859 which says that the PostScript name of the font is
 860 .IR psname .
 861 .
 862 It may also contain a command
 863 .IP
 864 .BI encoding\  enc_file
 865 .LP
 866 which says that
 867 the PostScript font should be reencoded using the encoding described in
 868 .IR enc_file ;
 869 this file should consist of a sequence of lines of the form:
 870 .IP
 871 .I
 872 pschar code
 873 .LP
 874 where
 875 .I pschar
 876 is the PostScript name of the character,
 877 and
 878 .I code
 879 is its position in the encoding expressed as a decimal integer; valid
 880 values are in the range 0 to\~255.
 881 .
 882 Lines starting with
 883 .B #
 884 and blank lines are ignored.
 885 .
 886 The code for each character given in the font file must correspond
 887 to the code for the character in encoding file, or to the code in the default
 888 encoding for the font if the PostScript font is not to be reencoded.
 889 .
 890 This code can be used with the
 891 .B \[rs]N
 892 escape sequence in
 893 .B troff
 894 to select the character,
 895 even if the character does not have a groff name.
 896 .
 897 Every character in the font file must exist in the PostScript font, and
 898 the widths given in the font file must match the widths used
 899 in the PostScript font.
 900 .
 901 .B grops
 902 will assume that a character with a groff name of
 903 .B space
 904 is blank (makes no marks on the page);
 905 it can make use of such a character to generate more efficient and
 906 compact PostScript output.
 907 .
 908 .LP
 909 Note that
 910 .B grops
 911 is able to display all glyphs in a PostScript font, not only 256.
 912 .I enc_file
 913 (or the default encoding if no encoding file specified) just defines the
 914 order of glyphs for the first 256 characters; all other glyphs are
 915 accessed with additional encoding vectors which
 916 .B grops
 917 produces on the fly.
 918 .
 919 .LP
 920 .B grops
 921 can automatically include the downloadable fonts necessary
 922 to print the document.
 923 Such fonts must be in PFA format.
 924 Use
 925 .BR pfbtops (@MAN1EXT@)
 926 to convert a Type\~1 font in PFB format.
 927 Any downloadable fonts which should, when required, be included by
 928 .B grops
 929 must be listed in the file
 930 .BR @FONTDIR@/devps/download ;
 931 this should consist of lines of the form
 932 .
 933 .IP
 934 .I
 935 font filename
 936 .
 937 .LP
 938 where
 939 .I font
 940 is the PostScript name of the font,
 941 and
 942 .I filename
 943 is the name of the file containing the font;
 944 lines beginning with
 945 .B #
 946 and blank lines are ignored;
 947 fields may be separated by tabs or spaces;
 948 .I filename
 949 will be searched for using the same mechanism that is used
 950 for groff font metric files.
 951 .
 952 The
 953 .B download
 954 file itself will also be searched for using this mechanism;
 955 currently, only the first found file in the font path is used.
 956 .
 957 .LP
 958 If the file containing a downloadable font or imported document
 959 conforms to the Adobe Document Structuring Conventions,
 960 then
 961 .B grops
 962 will interpret any comments in the files sufficiently to ensure that its
 963 own output is conforming.
 964 .
 965 It will also supply any needed font resources that are listed in the
 966 .B download
 967 file
 968 as well as any needed file resources.
 969 .
 970 It is also able to handle inter-resource dependencies.
 971 .
 972 For example, suppose that you have a downloadable font called Garamond,
 973 and also a downloadable font called Garamond-Outline
 974 which depends on Garamond
 975 (typically it would be defined to copy Garamond's font dictionary,
 976 and change the PaintType),
 977 then it is necessary for Garamond to appear before Garamond-Outline
 978 in the PostScript document.
 979 .
 980 .B grops
 981 will handle this automatically
 982 provided that the downloadable font file for Garamond-Outline
 983 indicates its dependence on Garamond by means of
 984 the Document Structuring Conventions,
 985 for example by beginning with the following lines
 986 .
 987 .IP
 988 .B
 989 %!PS-Adobe-3.0 Resource-Font
 990 .br
 991 .B
 992 %%DocumentNeededResources: font Garamond
 993 .br
 994 .B
 995 %%EndComments
 996 .br
 997 .B
 998 %%IncludeResource: font Garamond
 999 .
1000 .LP
1001 In this case both Garamond and Garamond-Outline would need to be listed
1002 in the
1003 .B download
1004 file.
1005 .
1006 A downloadable font should not include its own name in a
1007 .B %%Document\%Supplied\%Resources
1008 comment.
1009 .
1010 .LP
1011 .B grops
1012 will not interpret
1013 .B %%Document\%Fonts
1014 comments.
1015 .
1016 The
1017 .BR %%Document\%Needed\%Resources ,
1018 .BR %%Document\%Supplied\%Resources ,
1019 .BR %%Include\%Resource ,
1020 .BR %%Begin\%Resource ,
1021 and
1022 .BR %%End\%Resource
1023 comments
1024 (or possibly the old
1025 .BR %%Document\%Needed\%Fonts ,
1026 .BR %%Document\%Supplied\%Fonts ,
1027 .BR %%Include\%Font ,
1028 .BR %%Begin\%Font ,
1029 and
1030 .BR %%End\%Font
1031 comments)
1032 should be used.
1033 .
1034 .
1035 .SS Encapsulated PostScript
1036 .B grops
1037 itself doesn't emit bounding box information.
1038 .
1039 With the help of GhostScript the following commands will produce an
1040 encapsulated PS file
1041 .B foo.eps
1042 from input file
1043 .BR foo :
1044 .
1045 .IP
1046 .B
1047 groff -P-b16 foo > foo.ps
1048 .br
1049 .B
1050 gs -dNOPAUSE -sDEVICE=bbox -- foo.ps 2> foo.bbox
1051 .br
1052 .B
1053 cat foo.ps | sed \-e '/%%Orientation/rfoo.bbx' > foo.eps
1054 .br
1055 .B
1056 rm foo.bbx
1057 .br
1058 .
1059 .
1060 .
1061 .SS TrueType fonts
1062 TrueType fonts can be used with
1063 .B grops
1064 if converted first to
1065 .B "Type 42"
1066 format, an especial PostScript wrapper equivalent to the
1067 PFA format mentioned in
1068 .BR pfbtops (@MAN1EXT@).
1069 There are several different methods to generate a type42
1070 wrapper and most of them involve the use of a PostScript
1071 interpreter such as Ghostscript \(em see
1072 .BR gs (1).
1073 Yet, the easiest method involves the use of the application
1074 .BR ttftot42 .
1075 This program uses
1076 .BR freetype (3)
1077 (version 1.3.1) to generate type42
1078 font wrappers and well-formed AFM files that can be fed to
1079 the
1080 .BR afmtodit (@MAN1EXT@)
1081 script to create appropriate metric files.
1082 The resulting font wrappers should be added to the
1083 .B download
1084 file.
1085 .B ttftot42
1086 source code can be downloaded from
1087 .URL ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/ \
1088      ftp://\:www.giga.or.at/\:pub/\:nih/\:ttftot42/ .
1089 .
1090 .
1091 .SH ENVIRONMENT
1092 .TP
1093 .SM
1094 .B GROPS_PROLOGUE
1095 If this is set to
1096 .IR foo ,
1097 then
1098 .B grops
1099 will use the file
1100 .I foo
1101 (in the font path) instead of the default prologue file
1102 .BR prologue .
1103 .
1104 The option
1105 .B \-P
1106 overrides this environment variable.
1107 .
1108 .
1109 .SH FILES
1110 .Tp \w'\fB@FONTDIR@/devps/download'u+2n
1111 .B @FONTDIR@/devps/DESC
1112 Device description file.
1113 .
1114 .TP
1115 .BI @FONTDIR@/devps/ F
1116 Font description file for font
1117 .IR F .
1118 .
1119 .TP
1120 .B @FONTDIR@/devps/download
1121 List of downloadable fonts.
1122 .
1123 .TP
1124 .B @FONTDIR@/devps/text.enc
1125 Encoding used for text fonts.
1126 .
1127 .TP
1128 .B @MACRODIR@/ps.tmac
1129 Macros for use with
1130 .BR grops ;
1131 automatically loaded by
1132 .BR troffrc
1133 .
1134 .TP
1135 .B @MACRODIR@/pspic.tmac
1136 Definition of
1137 .B PSPIC
1138 macro,
1139 automatically loaded by
1140 .BR ps.tmac .
1141 .
1142 .TP
1143 .B @MACRODIR@/psold.tmac
1144 Macros to disable use of characters not present in older
1145 PostScript printers (e.g. `eth' or `thorn').
1146 .
1147 .TP
1148 .BI /tmp/grops XXXXXX
1149 Temporary file.
1150 .
1151 .
1152 .SH "SEE ALSO"
1153 .BR afmtodit (@MAN1EXT@),
1154 .BR groff (@MAN1EXT@),
1155 .BR @g@troff (@MAN1EXT@),
1156 .BR pfbtops (@MAN1EXT@),
1157 .BR groff_out (@MAN5EXT@),
1158 .BR groff_font (@MAN5EXT@),
1159 .BR groff_char (@MAN7EXT@),
1160 .BR groff_tmac (@MAN5EXT@)
1161 .
1162 .PP
1163 .URL "http://\:partners.adobe.com/\:public/\:developer/\:en/\:ps/\:5001.DSC_Spec.pdf" \
1164      "PostScript Language Document Structuring Conventions Specification"
1165 .
1166 .cp \n[grops_C]
1167 .
1168 .\" Local Variables:
1169 .\" mode: nroff
1170 .\" End: