src/devices/gropdf/gropdf.man

   1 .\" -*- nroff -*-
   2 .TH GROPDF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   3 .SH NAME
   4 gropdf \- PDF driver for groff
   5 .
   6 .
   7 .\" license
   8 .de co
   9 Copyright \[co] 2011-2014 Free Software Foundation, Inc.
  10
  11 Permission is granted to make and distribute verbatim copies of
  12 this manual provided the copyright notice and this permission notice
  13 are preserved on all copies.
  14
  15 Permission is granted to copy and distribute modified versions of this
  16 manual under the conditions for verbatim copying, provided that the
  17 entire resulting derived work is distributed under the terms of a
  18 permission notice identical to this one.
  19
  20 Permission is granted to copy and distribute translations of this
  21 manual into another language, under the above conditions for modified
  22 versions, except that this permission notice may be included in
  23 translations approved by the Free Software Foundation instead of in
  24 the original English.
  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 FT
  35 .  if '\\*(.T'ps' .ft \\$1
  36 .  if '\\*(.T'pdf' .ft \\$1
  37 ..
  38 .
  39 .\" --------------------------------------------------------------------
  40 .SH SYNOPSIS
  41 .\" --------------------------------------------------------------------
  42 .
  43 .SY gropdf
  44 .OP \-delvs
  45 .OP \-F dir
  46 \#.OP \-I dir
  47 .OP \-p papersize
  48 \#.OP \-w n
  49 .OP \-y foundry
  50 .OP \-u [cmapfile]
  51 .RI [ files
  52 .IR .\|.\|. ]
  53 .YS
  54 .
  55 .
  56 .LP
  57 It is possible to have whitespace between a command line option and its
  58 parameter.
  59 .
  60 .
  61 .\" --------------------------------------------------------------------
  62 .SH DESCRIPTION
  63 .\" --------------------------------------------------------------------
  64 .
  65 .B gropdf
  66 translates the output of GNU
  67 .B troff
  68 to PDF.
  69 .
  70 Normally
  71 .B gropdf
  72 should be invoked by using the groff command
  73 with a
  74 .B \-Tpdf
  75 option.
  76 .
  77 If no files are given,
  78 .B gropdf
  79 reads the standard input.
  80 .
  81 A filename of
  82 .B \-
  83 also causes
  84 .B gropdf
  85 to read the standard input.
  86 .
  87 PDF output is written to the standard output.
  88 .
  89 When
  90 .B gropdf
  91 is run by
  92 .B groff
  93 options can be passed to
  94 .B gropdf
  95 using
  96 .BR groff \[aq]s
  97 .B \-P
  98 option.
  99 .
 100 .
 101 .LP
 102 See section
 103 .B FONT INSTALLATION
 104 below for a guide how to install fonts for
 105 .BR gropdf .
 106 .
 107 .
 108 .\" --------------------------------------------------------------------
 109 .SH OPTIONS
 110 .\" --------------------------------------------------------------------
 111 .
 112 .TP
 113 .B \-d
 114 Include debug information as comments within the PDF.
 115 .
 116 Also produces an uncompressed PDF.
 117 .
 118 .TP
 119 .B \-e
 120 Force all fonts to be embedded in the PDF.
 121 .
 122 .TP
 123 .BI \-F dir
 124 Prepend directory
 125 .IB dir /dev name
 126 to the search path for font, and device description files;
 127 .I name
 128 is the name of the device, usually
 129 .BR pdf .
 130 .
 131 .\" .TP
 132 .\" .BI \-I dir
 133 .\" This option may be used to add a directory to the search path for
 134 .\" files on the command line and files named in
 135 .\" .B \[rs]X'ps: import'
 136 .\" and
 137 .\" .B \[rs]X'ps: file'
 138 .\" escapes.
 139 .\" .
 140 .\" The search path is initialized with the current directory.
 141 .\" .
 142 .\" This option may be specified more than once; the directories are then
 143 .\" searched in the order specified (but before the current directory).
 144 .\" .
 145 .\" If you want to make the current directory be read before other directories,
 146 .\" add
 147 .\" .B \-I.\&
 148 .\" at the appropriate place.
 149 .\" .
 150 .\" .IP
 151 .\" No directory search is performed for files with an absolute file name.
 152 .\" .
 153 .\" .TP
 154 .
 155 .TP
 156 .B \-l
 157 Print the document in landscape format.
 158 .
 159 .TP
 160 .BI \-p paper-size
 161 Set physical dimension of output medium.
 162 .
 163 This overrides the
 164 .BR papersize ,
 165 .BR paperlength ,
 166 and
 167 .B paperwidth
 168 commands in the
 169 .B DESC
 170 file; it accepts the same arguments as the
 171 .B papersize
 172 command.
 173 .
 174 See
 175 .B groff_font (@MAN5EXT@)
 176 for details.
 177 .
 178 .\" .TP
 179 .\" .BI \-w n
 180 .\" Lines should be drawn using a thickness of
 181 .\" .IR n \~\c
 182 .\" thousandths of an em.
 183 .\" .
 184 .\" If this option is not given, the line thickness defaults to 0.04\~em.
 185 .\" .
 186 .
 187 .TP
 188 .B \-v
 189 Print the version number.
 190 .
 191 .TP
 192 .BI \-y foundry
 193 Set the foundry to use for selecting fonts of the same name.
 194 .
 195 .TP
 196 .B \-e
 197 Forces
 198 .B gropdf
 199 to embed ALL fonts (even the 14 base PDF fonts).
 200 .
 201 .TP
 202 .B \-s
 203 Append a comment line to end of PDF showing statistics,
 204 i.e.\& number of pages in document.
 205 .
 206 Ghostscript\[aq]s
 207 .B ps2pdf
 208 complains about this line if it is included, but works anyway.
 209 .
 210 .TP
 211 .B \-u
 212 .TQ
 213 .BI \-u cmapfilename
 214 .B Gropdf
 215 normally includes a ToUnicode CMap with any font created using
 216 .B text.enc
 217 as the encoding file,
 218 this makes it easier to search for words which contain ligatures.
 219 .
 220 You can include your own CMap by specifying a
 221 .I cmapfilename
 222 or have no CMap at all by omitting the argument.
 223 .
 224 .
 225 .\" --------------------------------------------------------------------
 226 .SH USAGE
 227 .\" --------------------------------------------------------------------
 228 .
 229 The input to
 230 .B gropdf
 231 must be in the format output by
 232 .BR @g@troff (@MAN1EXT@).
 233 .
 234 This is described in
 235 .BR groff_out (@MAN5EXT@).
 236 .
 237 .
 238 .LP
 239 In addition, the device and font description files for the device used
 240 must meet certain requirements:
 241 .
 242 The resolution must be an integer multiple of\~72 times the
 243 .BR sizescale .
 244 .
 245 The
 246 .B pdf
 247 device uses a resolution of 72000 and a sizescale of 1000.
 248 .
 249 .
 250 .LP
 251 The device description file must contain a valid paper size; see
 252 .BR groff_font (@MAN5EXT@)
 253 for more information.
 254 .
 255 .B gropdf
 256 uses the same Type\~1 Adobe postscript fonts as the
 257 .B grops
 258 device driver.
 259 .
 260 Although the PDF Standard allows the use of other font types (like
 261 TrueType) this implementation only accepts the Type\~1 postscript
 262 font.
 263 .
 264 Fewer Type\~1 fonts are supported natively in PDF documents than the
 265 standard 35 fonts supported by
 266 .B grops
 267 and all postscript printers, but all the fonts are available since any
 268 which aren\[aq]t supported natively are automatically embedded in the
 269 PDF.
 270 .
 271 .
 272 .LP
 273 .B gropdf
 274 supports the concept of foundries, that is different versions of basically
 275 the same font.
 276 .
 277 During install a
 278 .B Foundry
 279 file controls where fonts are found and builds
 280 .B groff
 281 fonts from the files it discovers on your system.
 282 .
 283 .
 284 .LP
 285 Each font description file must contain a command
 286 .
 287 .IP
 288 .BI internalname\  psname
 289 .
 290 .LP
 291 which says that the PostScript name of the font is
 292 .IR psname .
 293 .
 294 Lines starting with
 295 .B #
 296 and blank lines are ignored.
 297 .
 298 The code for each character given in the font file must correspond
 299 to the code in the default encoding for the font.
 300 .
 301 This code can be used with the
 302 .B \[rs]N
 303 escape sequence in
 304 .B troff
 305 to select the character,
 306 even if the character does not have a groff name.
 307 .
 308 Every character in the font file must exist in the PostScript font, and
 309 the widths given in the font file must match the widths used
 310 in the PostScript font.
 311 .
 312 .
 313 .LP
 314 Note that
 315 .B gropdf
 316 is currently only able to display the first 256 glyphs in any font.
 317 This restriction will be lifted in a later version.
 318 .
 319 .
 320 .\" .LP
 321 .\" Note that
 322 .\" .B grops
 323 .\" is able to display all glyphs in a PostScript font, not only 256.
 324 .\" .I enc_file
 325 .\" (or the default encoding if no encoding file specified) just defines the
 326 .\" order of glyphs for the first 256 characters; all other glyphs are
 327 .\" accessed with additional encoding vectors which
 328 .\" .B grops
 329 .\" produces on the fly.
 330 .
 331 .
 332 .LP
 333 .B gropdf
 334 can automatically include the downloadable fonts necessary
 335 to print the document.
 336 .
 337 Fonts may be in PFA or PFB format.
 338 .LP
 339 .
 340 Any downloadable fonts which should, when required, be included by
 341 .B gropdf
 342 must be listed in the file
 343 .BR @FONTDIR@/devpdf/download ;
 344 this should consist of lines of the form
 345 .
 346 .IP
 347 .I
 348 foundry font filename
 349 .
 350 .LP
 351 where
 352 .I foundry
 353 is the foundry name or blank for the default foundry.
 354 .
 355 .I font
 356 is the PostScript name of the font,
 357 and
 358 .I filename
 359 is the name of the file containing the font;
 360 lines beginning with
 361 .B #
 362 and blank lines are ignored;
 363 fields must be separated by tabs
 364 (spaces are
 365 .B not
 366 allowed);
 367 .I filename
 368 is searched for using the same mechanism that is used
 369 for groff font metric files.
 370 .
 371 The
 372 .B download
 373 file itself is also searched for using this mechanism;
 374 currently, only the first found file in the font path is used.
 375 .
 376 Foundry names are usually a single character (such as \[oq]U\[cq] for
 377 the URW Foundry) or blank for the default foundry.
 378 .
 379 This default uses the same fonts as
 380 .B ghostscript
 381 uses when it embeds fonts in a PDF file.
 382 .
 383 .
 384 .LP
 385 In the default setup there are styles called
 386 .BR R ,
 387 .BR I ,
 388 .BR B ,
 389 and
 390 .B BI
 391 mounted at font positions 1 to\~4.
 392 .
 393 The fonts are grouped into families
 394 .BR A ,
 395 .BR BM ,
 396 .BR C ,
 397 .BR H ,
 398 .BR HN ,
 399 .BR N ,
 400 .BR P ,
 401 and\~\c
 402 .B T
 403 having members in each of these styles:
 404 .
 405 .RS
 406 .TP
 407 .B AR
 408 .FT AR
 409 AvantGarde-Book
 410 .FT
 411 .
 412 .TQ
 413 .B AI
 414 .FT AI
 415 AvantGarde-BookOblique
 416 .FT
 417 .
 418 .TQ
 419 .B AB
 420 .FT AB
 421 AvantGarde-Demi
 422 .FT
 423 .
 424 .TQ
 425 .B ABI
 426 .FT ABI
 427 AvantGarde-DemiOblique
 428 .FT
 429 .
 430 .TQ
 431 .B BMR
 432 .FT BMR
 433 Bookman-Light
 434 .FT
 435 .
 436 .TQ
 437 .B BMI
 438 .FT BMI
 439 Bookman-LightItalic
 440 .FT
 441 .
 442 .TQ
 443 .B BMB
 444 .FT BMB
 445 Bookman-Demi
 446 .FT
 447 .
 448 .TQ
 449 .B BMBI
 450 .FT BMBI
 451 Bookman-DemiItalic
 452 .FT
 453 .
 454 .TQ
 455 .B CR
 456 .FT CR
 457 Courier
 458 .FT
 459 .
 460 .TQ
 461 .B CI
 462 .FT CI
 463 Courier-Oblique
 464 .FT
 465 .
 466 .TQ
 467 .B CB
 468 .FT CB
 469 Courier-Bold
 470 .FT
 471 .
 472 .TQ
 473 .B CBI
 474 .FT CBI
 475 Courier-BoldOblique
 476 .FT
 477 .
 478 .TQ
 479 .B HR
 480 .FT HR
 481 Helvetica
 482 .FT
 483 .
 484 .TQ
 485 .B HI
 486 .FT HI
 487 Helvetica-Oblique
 488 .FT
 489 .
 490 .TQ
 491 .B HB
 492 .FT HB
 493 Helvetica-Bold
 494 .FT
 495 .
 496 .TQ
 497 .B HBI
 498 .FT HBI
 499 Helvetica-BoldOblique
 500 .FT
 501 .
 502 .TQ
 503 .B HNR
 504 .FT HNR
 505 Helvetica-Narrow
 506 .FT
 507 .
 508 .TQ
 509 .B HNI
 510 .FT HNI
 511 Helvetica-Narrow-Oblique
 512 .FT
 513 .
 514 .TQ
 515 .B HNB
 516 .FT HNB
 517 Helvetica-Narrow-Bold
 518 .FT
 519 .
 520 .TQ
 521 .B HNBI
 522 .FT HNBI
 523 Helvetica-Narrow-BoldOblique
 524 .FT
 525 .
 526 .TQ
 527 .B NR
 528 .FT NR
 529 NewCenturySchlbk-Roman
 530 .FT
 531 .
 532 .TQ
 533 .B NI
 534 .FT NI
 535 NewCenturySchlbk-Italic
 536 .FT
 537 .
 538 .TQ
 539 .B NB
 540 .FT NB
 541 NewCenturySchlbk-Bold
 542 .FT
 543 .
 544 .TQ
 545 .B NBI
 546 .FT NBI
 547 NewCenturySchlbk-BoldItalic
 548 .FT
 549 .
 550 .TQ
 551 .B PR
 552 .FT PR
 553 Palatino-Roman
 554 .FT
 555 .
 556 .TQ
 557 .B PI
 558 .FT PI
 559 Palatino-Italic
 560 .FT
 561 .
 562 .TQ
 563 .B PB
 564 .FT PB
 565 Palatino-Bold
 566 .FT
 567 .
 568 .TQ
 569 .B PBI
 570 .FT PBI
 571 Palatino-BoldItalic
 572 .FT
 573 .
 574 .TQ
 575 .B TR
 576 .FT TR
 577 Times-Roman
 578 .FT
 579 .
 580 .TQ
 581 .B TI
 582 .FT TI
 583 Times-Italic
 584 .FT
 585 .
 586 .TQ
 587 .B TB
 588 .FT TB
 589 Times-Bold
 590 .FT
 591 .
 592 .TQ
 593 .B TBI
 594 .FT TBI
 595 Times-BoldItalic
 596 .FT
 597 .RE
 598 .
 599 .
 600 .LP
 601 There is also the following font which is not a member of a family:
 602 .
 603 .RS
 604 .TP
 605 .B ZCMI
 606 .FT ZCMI
 607 ZapfChancery-MediumItalic
 608 .FT
 609 .RE
 610 .
 611 .
 612 .LP
 613 There are also some special fonts called
 614 .B S
 615 for the PS Symbol font.
 616 .
 617 The lower case greek characters are automatically slanted (to match
 618 the SymbolSlanted font (SS) available to postscript).
 619 .
 620 Zapf Dingbats is available as
 621 .BR ZD ,
 622 the "hand pointing left" glyph (\[rs][lh]) is available since it has
 623 been defined using the \[rs]X'pdf: xrev' extension which reverses the
 624 direction of letters within words.
 625 .
 626 .
 627 .LP
 628 The default color for
 629 .B \[rs]m
 630 and
 631 .B \[rs]M
 632 is black; for colors defined in the \[oq]rgb\[cq] color space
 633 .B setrgbcolor
 634 is used, for \[oq]cmy\[cq] and \[oq]cmyk\[cq]
 635 .BR setcmykcolor ,
 636 and for \[oq]gray\[cq]
 637 .BR setgray .
 638 .
 639 Note that
 640 .B setcmykcolor
 641 is a PostScript LanguageLevel\~2 command and thus not available on
 642 some older printers.
 643 .
 644 .
 645 .LP
 646 .B gropdf
 647 understands some of the X\~commands produced using the
 648 .B \[rs]X
 649 escape sequences supported by
 650 .B grops.
 651 Specifically, the following is supported.
 652 .
 653 .TP
 654 .B "\[rs]X'ps: invis'"
 655 Suppress output.
 656 .
 657 .TP
 658 .B "\[rs]X'ps: endinvis'"
 659 Stop suppressing output.
 660 .
 661 .TP
 662 .B "\[rs]X'ps: exec gsave currentpoint 2 copy translate \fIn\fP rotate neg exch neg exch translate'"
 663 where
 664 .I n
 665 is the angle of rotation.
 666 This is to support the
 667 .I align
 668 command in
 669 .BR gpic .
 670 .
 671 .TP
 672 .B "\[rs]X'ps: exec grestore'"
 673 Again used by
 674 .B gpic
 675 to restore after rotation.
 676 .
 677 .TP
 678 .BI "\[rs]X'ps: exec " "n " "setlinejoin'"
 679 where
 680 .I n
 681 can be one of the following values.
 682 .IP
 683 0 = Miter join
 684 .br
 685 1 = Round join
 686 .br
 687 2 = Bevel join
 688 .
 689 .TP
 690 .BI "\[rs]X'ps: exec " "n " "setlinecap'"
 691 where
 692 .I n
 693 can be one of the following values.
 694 .IP
 695 0 = Butt cap
 696 .br
 697 1 = Round cap, and
 698 .br
 699 2 = Projecting square cap
 700 .
 701 .
 702 .LP
 703 .TP
 704 .B "\[rs]X'ps: ... pdfmark'"
 705 All the
 706 .I pdfmark
 707 macros installed by using
 708 .I \-m pdfmark
 709 or
 710 .I \-m mspdf
 711 (see documentation in \[oq]pdfmark.pdf\[cq]).
 712 .
 713 A subset of these macros are installed automatically when you use
 714 .B \-Tpdf
 715 so you should not need to use \[oq]\-m pdfmark\[cq] for using most of
 716 the PDF functionality.
 717 .
 718 .
 719 .LP
 720 All other
 721 .B ps:
 722 tags are silently ignored.
 723 .
 724 .
 725 .LP
 726 One
 727 .B \[rs]X
 728 special used by the DVI driver is also recognised:
 729 .
 730 .TP
 731 .BI \[rs]X'papersize= paper-size '
 732 where the
 733 .I paper-size
 734 parameter is the same as the
 735 .B papersize
 736 command.
 737 .
 738 See
 739 .BR groff_font (@MAN5EXT@)
 740 for details.
 741 .
 742 This means that you can alter the page size at will within the PDF file
 743 being created by
 744 .BR gropdf .
 745 .
 746 If you do want to change the paper size, it must be done before you start
 747 creating the page.
 748 .
 749 .LP
 750 In addition,
 751 .B gropdf
 752 supports its own suite of
 753 .B pdf:
 754 tags.
 755 .
 756 The following tags are supported:
 757 .
 758 .TP
 759 .BI "\[rs]X'pdf: pdfpic " "file alignment width height line-length" '
 760 Place an image of the specified
 761 .I width
 762 containing the PDF drawing from file
 763 .I file
 764 of desired
 765 .I width
 766 and
 767 .I height
 768 (if
 769 .I height
 770 is missing or zero then it is scaled proportionally).
 771 .
 772 If
 773 .I alignment
 774 is
 775 .B \-L
 776 the drawing is left aligned.
 777 .
 778 If it is
 779 .B \-C
 780 or
 781 .B \-R
 782 a
 783 .I linelength
 784 greater than the width of the drawing is required as well.
 785 .
 786 If
 787 .I width
 788 is specified as zero then the width is scaled in proportion to the height.
 789 .
 790 .\" .IP
 791 .\" See
 792 .\" .BR groff_tmac (@MAN5EXT@)
 793 .\" for a description of the
 794 .\" .B PSPIC
 795 .\" macro which provides a convenient high-level interface for inclusion of
 796 .\" PostScript graphics.
 797 .
 798 .TP
 799 .B \[rs]X'pdf: xrev'
 800 This toggles a flag which reverses the direction of printing
 801 .IR "letter by letter" ,
 802 i.e., each separate letter is reversed, not the entire word.
 803 .
 804 This is useful for reversing the direction of glyphs in the Dingbats font.
 805 .
 806 To return to normal printing repeat the command again.
 807 .
 808 .TP
 809 .BI "\[rs]X'pdf: markstart " "/ANN definition" '
 810 The macros which support PDF Bookmarks use this call internally to
 811 start the definition of bookmark hotspot (user will have called
 812 \[oq].pdfhref\~L\[cq] with the text which will become the \[oq]hot
 813 spot\[cq] region).
 814 .
 815 Normally this is never used except from within the pdfmark macros.
 816 .
 817 .TP
 818 .B \[rs]X'pdf: markend'
 819 The macros which support PDF Bookmarks use this call internally to
 820 stop the definition of bookmark hotspot (user will have called
 821 \[oq].pdfhref\~L\[cq] with the text which will become the \[oq]hot
 822 spot\[cq] region).
 823 .
 824 Normally this is never used except from within the pdfmark macros.
 825 .
 826 .TP
 827 .B \[rs]X'pdf: marksuspend'
 828 .TQ
 829 .B \[rs]X'pdf: markrestart'
 830 If you are using page traps to produce headings, footings, etc., you
 831 need to use these in case a \[oq]hot spot\[cq] crosses a page
 832 boundary, otherwise any text output by the heading or footing macro
 833 will be marked as part of the \[oq]hot spot\[cq].
 834 .
 835 To stop this happening just place \[oq].pdfmarksuspend\[cq] and
 836 \[oq].pdfmarkrestart\[cq] at the start and end of the page trap macro,
 837 respectively.
 838 .
 839 (These are just convenience macros which emit the \[rs]X code.
 840 .
 841 These macros must only be used within page traps.)
 842 .
 843 .
 844 .\" --------------------------------------------------------------------
 845 .SS Importing graphics
 846 .\" --------------------------------------------------------------------
 847 .
 848 .B gropdf
 849 only supports importing other PDF files as graphics.
 850 .
 851 But that PDF file may contain any of the graphic formats supported by
 852 the PDF standard (such as JPEG, PNG, GIF, etc.).
 853 .
 854 So any application which outputs PDF can be used as an embedded file
 855 in
 856 .BR gropdf .
 857 .
 858 The PDF file you wish to insert must be a single page and the drawing
 859 must just fit inside the media size of the PDF file.
 860 .
 861 So, in
 862 .BR inkscape (1)
 863 or
 864 .BR gimp (1)
 865 (for example) make sure the canvas size just fits the image.
 866 .
 867 .
 868 .LP
 869 The PDF parser used in
 870 .B gropdf
 871 has not been rigorously tested with all possible applications which
 872 produce PDFs.
 873 .
 874 If you find a single page PDF which fails to import properly, it is
 875 worth running it through the
 876 .
 877 .BR pdftk (1)
 878 program by issuing the command:
 879 .
 880 .
 881 .RS
 882 .LP
 883 .B pdftk
 884 .I oldfile.pdf
 885 .B output
 886 .I newfile.pdf
 887 .RE
 888 .
 889 .
 890 .LP
 891 You may find that
 892 .I newfile.pdf
 893 will now load successfully.
 894 .
 895 .
 896 .\" --------------------------------------------------------------------
 897 .SS TrueType and other font formats
 898 .\" --------------------------------------------------------------------
 899 .
 900 .B gropdf
 901 does not support any other fonts except Adobe Type 1 (PFA or PFB).
 902 .
 903 .
 904 .\" --------------------------------------------------------------------
 905 .SH FONT INSTALLATION
 906 .\" --------------------------------------------------------------------
 907 .
 908 This section gives a summary of the above explanations; it can serve
 909 as a step-by-step font installation guide for
 910 .BR gropdf .
 911 .
 912 .ds BU \[bu]\ \ \"
 913 .de LI
 914 .IP "" 4
 915 \h'-\w'\*[BU]'u'\*[BU]\c
 916 ..
 917 .LI
 918 Convert your font to something groff understands.
 919 .
 920 This is either a PostScript Type\~1 font in either PFA or PFB,
 921 together with an AFM file.
 922 .
 923 .IP
 924 The very first line in a PFA/PFB file contains this:
 925 .
 926 .RS
 927 .IP
 928 .B %!PS-AdobeFont-1.0:
 929 .RE
 930 .
 931 .IP
 932 A PFB file has this also in the first line, but the string is
 933 preceded with some binary bytes.
 934 .
 935 .LI
 936 Convert the AFM file to a groff font description file with the
 937 .BR \%afmtodit (@MAN1EXT@)
 938 program.
 939 .
 940 An example call is
 941 .
 942 .RS
 943 .IP
 944 afmtodit Foo-Bar-Bold.afm map/textmap FBB
 945 .RE
 946 .
 947 .IP
 948 which converts the metric file \[oq]Foo-Bar-Bold.afm\[cq] to the groff
 949 font \[oq]FBB\[cq].
 950 .
 951 If you have a font family which comes with normal, bold, italic, and
 952 bold italic faces, it is recommended to use the letters
 953 .BR R ,
 954 .BR B ,
 955 .BR I ,
 956 and
 957 .BR BI ,
 958 respectively, as postfixes in the groff font names to make groff\[aq]s
 959 \[oq].fam\[cq] request work.
 960 .
 961 An example is groff\[aq]s built-in Times-Roman font: The font family
 962 name is
 963 .BR T ,
 964 and the groff font names are
 965 .BR TR ,
 966 .BR TB ,
 967 .BR TI ,
 968 and
 969 .BR TBI .
 970 .
 971 .LI
 972 Install both the groff font description files and the fonts in a
 973 \[oq]devpdf\[cq] subdirectory of the font path which groff finds.
 974 .
 975 See the
 976 .B ENVIRONMENT
 977 section in the
 978 .BR troff (@MAN1EXT@)
 979 man page which lists the actual value of the font path.
 980 .
 981 Note that groff doesn\[aq]t use the AFM files (but it is a good idea to
 982 store them anyway).
 983 .
 984 .LI
 985 Register all fonts which must be downloaded to the printer in the
 986 \[oq]devpdf/download\[cq] file.
 987 .
 988 Only the first occurrence of this file in the font path is read.
 989 .
 990 This means that you should copy the default \[oq]download\[cq] file to
 991 the first directory in your font path and add your fonts there.
 992 .
 993 To continue the above example we assume that the PS font name for
 994 Foo-Bar-Bold.pfa is \[oq]XY-Foo-Bar-Bold\[cq] (the PS font name is
 995 stored in the
 996 .B internalname
 997 field in the \[oq]FBB\[cq] file) and belongs to foundry \[oq]F\[]cq]
 998 thus the following line should be added to \[oq]download\[cq]:
 999 .
1000 .RS
1001 .IP
1002 .B F XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
1003 .
1004 .
1005 .LP
1006 Use a tab character to separate the fields, and the \[oq]foundry\[cq]
1007 field should be null for the default foundry.
1008 .RE
1009 .
1010 .
1011 .\" --------------------------------------------------------------------
1012 .SH ENVIRONMENT
1013 .\" --------------------------------------------------------------------
1014 .
1015 .TP
1016 .SM
1017 .B GROFF_FONT_PATH
1018 A list of directories in which to search for the
1019 .BI dev name
1020 directory in addition to the default ones.
1021 .
1022 If, in the \[oq]download\[cq] file, the
1023 font file has been specified with a full path, no directories are searched.
1024 .
1025 See
1026 .BR @g@troff (@MAN1EXT@)
1027 and
1028 .BR \%groff_font (@MAN5EXT@)
1029 for more details.
1030 .
1031 .
1032 .\" --------------------------------------------------------------------
1033 .SH FILES
1034 .\" --------------------------------------------------------------------
1035 .
1036 .Tp \w'\fB@FONTDIR@/devpdf/download'u+2n
1037 .B @FONTDIR@/devpdf/DESC
1038 Device description file.
1039 .
1040 .TP
1041 .BI @FONTDIR@/devpdf/ F
1042 Font description file for font\~\c
1043 .IR F .
1044 .
1045 .TP
1046 .BI @FONTDIR@/devpdf/ U-F
1047 Font description file for font\~\c
1048 .I F
1049 (using foundry\~\c
1050 .I U
1051 rather than the default foundry).
1052 .
1053 .TP
1054 .B @FONTDIR@/devpdf/download
1055 List of downloadable fonts.
1056 .
1057 .TP
1058 .B @FONTDIR@/devpdf/Foundry
1059 A Perl script used during install to locate suitable fonts.
1060 .
1061 .TP
1062 .B @FONTDIR@/devpdf/enc/text.enc
1063 Encoding used for text fonts.
1064 .
1065 .TP
1066 .B @MACRODIR@/pdf.tmac
1067 Macros for use with
1068 .BR gropdf ;
1069 automatically loaded by
1070 .BR troffrc .
1071 .
1072 .\" .TP
1073 .\" .B @MACRODIR@/pspic.tmac
1074 .\" Definition of
1075 .\" .B PSPIC
1076 .\" macro,
1077 .\" automatically loaded by
1078 .\" .BR ps.tmac .
1079 .\" .
1080 .
1081 .
1082 .\" --------------------------------------------------------------------
1083 .SH "SEE ALSO"
1084 .\" --------------------------------------------------------------------
1085 .
1086 .ad l
1087 .
1088 .BR \%afmtodit (@MAN1EXT@),
1089 .BR groff (@MAN1EXT@),
1090 .BR grops (@MAN1EXT@),
1091 .BR @g@troff (@MAN1EXT@),
1092 .BR grops (@MAN1EXT@),
1093 .BR \%pfbtops (@MAN1EXT@),
1094 .BR \%groff_out (@MAN5EXT@),
1095 .BR \%groff_font (@MAN5EXT@),
1096 .BR \%groff_char (@MAN7EXT@),
1097 .BR \%groff_tmac (@MAN5EXT@)
1098 .
1099 .
1100 .\" --------------------------------------------------------------------
1101 .SH LICENSE
1102 .\" --------------------------------------------------------------------
1103 .co
1104 .
1105 .
1106 .\" Local Variables:
1107 .\" mode: nroff
1108 .\" End: