man/groff_font.5.man

   1 .TH GROFF_FONT @MAN5EXT@ "@MDATE@" "groff @VERSION@"
   2 .SH NAME
   3 groff_font \- format of groff device and font description files
   4 .
   5 .
   6 .\" ====================================================================
   7 .\" Legal Terms
   8 .\" ====================================================================
   9 .\"
  10 .\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
  11 .\"
  12 .\" This file is part of groff (GNU roff), which is a free software
  13 .\" project.
  14 .\"
  15 .\" You can redistribute it and/or modify it under the terms of the GNU
  16 .\" General Public License as published by the Free Software Foundation,
  17 .\" either version 2 of the License, or (at your option) any later
  18 .\" version.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public License
  21 .\" along with this program.  If not, see
  22 .\" <http://www.gnu.org/licenses/gpl-2.0.html>.
  23 .
  24 .
  25 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
  26 .do nr groff_font_C \n[.C]
  27 .cp 0
  28 .
  29 .
  30 .\" ====================================================================
  31 .SH DESCRIPTION
  32 .\" ====================================================================
  33 .
  34 The groff font format is roughly a superset of the ditroff
  35 font format.
  36 .
  37 The font files for device
  38 .I name
  39 are stored in a directory
  40 .IR dev name.
  41 .
  42 There are two types of file:
  43 a device description file called
  44 .I DESC
  45 and for each
  46 .RI font \~F ,
  47 a font file called\~F.
  48 .
  49 These are text files;
  50 unlike the ditroff font format,
  51 there is no associated binary format.
  52 .
  53 .
  54 .\" ====================================================================
  55 .SS DESC file format
  56 .\" ====================================================================
  57 .
  58 The
  59 .I DESC
  60 file can contain the following types of line as shown below.
  61 .
  62 Later entries in the file override previous values.
  63 .
  64 .LP
  65 Empty lines are ignored.
  66 .
  67 .TP
  68 .B charset
  69 This line and everything following in the file are ignored.
  70 .
  71 It is allowed for the sake of backwards compatibility.
  72 .
  73 .TP
  74 .BI "family " fam
  75 The default font family is
  76 .IR fam .
  77 .
  78 .TP
  79 .BI "fonts " "n F1 F2 F3 \|.\|.\|.\| Fn"
  80 Fonts
  81 .IR F1 ", \|.\|.\|., " Fn
  82 are mounted in the font positions
  83 .IR m "\|+\|1, \|.\|.\|., " m \|+\| n
  84 where
  85 .I m
  86 is the number of styles.
  87 .
  88 This command may extend over more than one line.
  89 .
  90 A font name of\~\c
  91 .B 0
  92 causes no font to be mounted on the corresponding font position.
  93 .
  94 .TP
  95 .BI "hor " n
  96 The horizontal resolution is
  97 .IR n \~\c
  98 machine units.
  99 .
 100 .TP
 101 .BI "image_generator "  string
 102 Needed for
 103 .B \%grohtml
 104 only.
 105 .
 106 It specifies the program to generate PNG images from
 107 PostScript input.
 108 .
 109 Under GNU/Linux this is usually
 110 .I gs
 111 but under other systems (notably cygwin) it might be set to another
 112 name.
 113 .
 114 .TP
 115 .BI "paperlength " n
 116 The physical vertical dimension of the output medium in machine units.
 117 .
 118 This isn't used by
 119 .B troff
 120 itself but by output devices.
 121 .
 122 Deprecated.
 123 .
 124 Use
 125 .B papersize
 126 instead.
 127 .
 128 .TP
 129 .BI "papersize " string
 130 Select a paper size.
 131 .
 132 Valid values for
 133 .I string
 134 are the ISO paper types A0\[en]A7, B0\[en]B7, C0\[en]C7, D0\[en]D7,
 135 DL, and the US paper
 136 types letter, legal, tabloid, ledger, statement, executive, com10, and
 137 monarch.
 138 .
 139 Case is not significant for
 140 .I string
 141 if it holds predefined paper types.
 142 .
 143 Alternatively,
 144 .I string
 145 can be a file name (e.g.\&
 146 .IR /etc/papersize );
 147 if the file can be opened,
 148 .B groff
 149 reads the first line and tests for the above paper sizes.
 150 .
 151 Finally,
 152 .I string
 153 can be a custom paper size in the format
 154 .IB length , width
 155 (no spaces before and after the comma).
 156 .
 157 Both
 158 .I length
 159 and
 160 .I width
 161 must have a unit appended; valid values are \[oq]i\[cq] for inches,
 162 \[oq]c\[cq] for centimeters, \[oq]p\[cq] for points, and \[oq]P\[cq]
 163 for picas.
 164 .
 165 Example:
 166 .BR 12c,235p .
 167 .
 168 An argument which starts with a digit is always treated as a custom
 169 paper format.
 170 .
 171 .B papersize
 172 sets both the vertical and horizontal dimension of the output medium.
 173 .
 174 .IP
 175 More than one argument can be specified;
 176 .B groff
 177 scans from left to right and uses the first valid paper specification.
 178 .
 179 .TP
 180 .BI "paperwidth " n
 181 The physical horizontal dimension of the output medium in machine units.
 182 .
 183 Deprecated.
 184 .
 185 Use
 186 .B papersize
 187 instead.
 188 .
 189 This isn't used by
 190 .B troff
 191 itself but by output devices.
 192 .
 193 .TP
 194 .B pass_filenames
 195 Make troff tell the driver the source file name being processed.
 196 .
 197 This is achieved by another tcommand:
 198 .BR F \~\c
 199 .IR filename .
 200 .
 201 .TP
 202 .BI "postpro " program
 203 Use
 204 .I program
 205 as the postprocessor.
 206 .
 207 .TP
 208 .BI "prepro " program
 209 Call
 210 .I program
 211 as a preprocessor.
 212 .
 213 .TP
 214 .BI "print "  program
 215 Use
 216 .I program
 217 as the spooler program for printing.
 218 .
 219 If omitted, the
 220 .B \-l
 221 and
 222 .B \-L
 223 options of
 224 .B groff
 225 are ignored.
 226 .
 227 .TP
 228 .BI "res " n
 229 There are
 230 .I n
 231 machine units per inch.
 232 .
 233 .TP
 234 .BI "sizes " "s1 s2 \|.\|.\|.\| sn " 0
 235 This means that the device has fonts at
 236 .IR s1 ,
 237 .IR s2 ", \|.\|.\|., " sn
 238 scaled points.
 239 .
 240 The list of sizes must be terminated by a
 241 .BR 0 .
 242 .
 243 Each
 244 .I si
 245 can also be a range of sizes
 246 .IR m \(en n .
 247 .
 248 The list can extend over more than one line.
 249 .
 250 .TP
 251 .BI "sizescale " n
 252 The scale factor for point sizes.
 253 .
 254 By default this has a value of 1.
 255 .
 256 One
 257 .I
 258 scaled point
 259 is equal to
 260 one
 261 .RI point\|/\| n .
 262 .
 263 The arguments to the
 264 .B unitwidth
 265 and
 266 .B sizes
 267 commands are given in scaled points.
 268 .
 269 .TP
 270 .BI "styles " "S1 S2 \|.\|.\|.\| Sm"
 271 The first
 272 .I m
 273 font positions are associated with styles
 274 .IR S1 ", \|.\|.\|., " Sm .
 275 .
 276 .TP
 277 .B tcommand
 278 This means that the postprocessor can handle the
 279 .B t
 280 and\~\c
 281 .B u
 282 output commands.
 283 .
 284 .TP
 285 .B unicode
 286 Indicate that the output device supports the complete Unicode
 287 repertoire.
 288 .
 289 Useful only for devices which produce
 290 .I character entities
 291 instead of glyphs.
 292 .
 293 .IP
 294 If
 295 .B unicode
 296 is present, no
 297 .B charset
 298 section is required in the font description files since the Unicode
 299 handling built into
 300 .B groff
 301 is used.
 302 .
 303 However, if there are entries in a
 304 .B charset
 305 section, they either override the default mappings for those
 306 particular characters or add new mappings (normally for composite
 307 characters).
 308 .
 309 .IP
 310 This is used for
 311 .BR \-Tutf8 ,
 312 .BR \-Thtml ,
 313 and
 314 .BR \-Txhtml .
 315 .
 316 .TP
 317 .BI "unitwidth " n
 318 Quantities in the font files are given in machine units
 319 for fonts whose point size is
 320 .IR n \~\c
 321 scaled points.
 322 .
 323 .TP
 324 .B unscaled_charwidths
 325 Make the font handling module always return unscaled glyph widths.
 326 .
 327 Needed for the
 328 .B \%grohtml
 329 device.
 330 .
 331 .TP
 332 .B use_charnames_in_special
 333 This command indicates that troff should encode named glyphs inside
 334 special commands.
 335 .
 336 .TP
 337 .BI "vert " n
 338 The vertical resolution is
 339 .IR n \~\c
 340 machine units.
 341 .
 342 .LP
 343 The
 344 .BR res ,
 345 .BR unitwidth ,
 346 .BR fonts ,
 347 and
 348 .B sizes
 349 lines are compulsory.
 350 .
 351 Not all commands in the
 352 .I DESC
 353 file are used by
 354 .B troff
 355 itself; some of the keywords (or even additional ones) are used by
 356 postprocessors to store arbitrary information about the device.
 357 .
 358 .LP
 359 Here a list of obsolete keywords which are recognized by
 360 .B groff
 361 but completely ignored:
 362 .BR spare1 ,
 363 .BR spare2 ,
 364 .BR biggestfont .
 365 .
 366 .
 367 .\" ====================================================================
 368 .SS Font file format
 369 .\" ====================================================================
 370 .
 371 A font file has two sections; empty lines are ignored in both of them.
 372 .
 373 .LP
 374 The first section is a sequence of lines each containing a sequence of
 375 blank delimited words; the first word in the line is a key, and
 376 subsequent words give a value for that key.
 377 .
 378 .TP
 379 .BI "ligatures " "lig1 lig2 \|.\|.\|.\| lign \fR[" 0 \fR]
 380 Glyphs
 381 .IR lig1 ,
 382 .IR lig2 ", \|.\|.\|., " lign
 383 are ligatures; possible ligatures are
 384 .BR ff ,
 385 .BR fi ,
 386 .BR fl ,
 387 .BR ffi ,
 388 and
 389 .BR ffl .
 390 .
 391 For backwards compatibility, the list of ligatures may be terminated
 392 with a\~\c
 393 .BR 0 .
 394 .
 395 The list of ligatures may not extend over more than one line.
 396 .
 397 .TP
 398 .BI "name " F
 399 The name of the font is\~\c
 400 .IR F .
 401 .
 402 .TP
 403 .BI "slant " n
 404 The glyphs of the font have a slant of
 405 .IR n \~\c
 406 degrees.
 407 .
 408 (Positive means forward.)
 409 .
 410 .TP
 411 .BI "spacewidth "  n
 412 The normal width of a space is\~\c
 413 .IR n .
 414 .
 415 .TP
 416 .B special
 417 The font is
 418 .IR special ;
 419 this means that when a glyph is requested that is not present in
 420 the current font, it is searched for in any special fonts that are
 421 mounted.
 422 .
 423 .LP
 424 Other commands are ignored by
 425 .B troff
 426 but may be used by postprocessors to store arbitrary information
 427 about the font in the font file.
 428 .
 429 .LP
 430 The first section can contain comments which start with the
 431 .B #
 432 character and extend to the end of a line.
 433 .
 434 .LP
 435 The second section contains one or two subsections.
 436 .
 437 It must contain a
 438 .I charset
 439 subsection
 440 and it may also contain a
 441 .I kernpairs
 442 subsection.
 443 .
 444 These subsections can appear in any order.
 445 .
 446 Each subsection starts with a word on a line by itself.
 447 .
 448 .LP
 449 The word
 450 .B charset
 451 starts the charset subsection.
 452 .
 453 The
 454 .B charset
 455 line is followed by a sequence of lines.
 456 .
 457 Each line gives information for one glyph.
 458 .
 459 A line comprises a number of fields separated
 460 by blanks or tabs.
 461 .
 462 The format is
 463 .
 464 .IP
 465 .I name metrics type code
 466 .RI [ entity_name ]
 467 .RB [ \-\-
 468 .IR comment ]
 469 .
 470 .LP
 471 .I name
 472 identifies the glyph:
 473 if
 474 .I name
 475 is a single glyph
 476 .I c
 477 then it corresponds to the groff input character
 478 .IR c ;
 479 if it is of the form
 480 .BI \[rs] c
 481 where c is a single character, then it
 482 corresponds to the special character
 483 .BI \[rs][ c ]\fR;
 484 otherwise it corresponds to the groff input character
 485 .BI \[rs][ name ]\fR.
 486 .
 487 If it is exactly two characters
 488 .I xx
 489 it can be entered as
 490 .BI \[rs]( xx\fR.
 491 .
 492 Note that single-letter special characters can't be accessed as
 493 .BI \[rs] c\fR;
 494 the only exception is \[oq]\[rs]\-\[cq] which is identical to
 495 \[oq]\[rs][\-]\[cq].
 496 .
 497 The name
 498 .B \-\-\-
 499 is special and indicates that the glyph is unnamed;
 500 such glyphs can only be used by means of the
 501 .B \[rs]N
 502 escape sequence in
 503 .BR troff .
 504 .
 505 .LP
 506 The
 507 .I type
 508 field gives the glyph type:
 509 .
 510 .TP
 511 1
 512 means the glyph has a descender, for example, \[oq]p\[cq];
 513 .
 514 .TP
 515 2
 516 means the glyph has an ascender, for example, \[oq]b\[cq];
 517 .
 518 .TP
 519 3
 520 means the glyph has both an ascender and a descender, for example,
 521 \[oq](\[cq].
 522 .
 523 .LP
 524 The
 525 .I code
 526 field gives the code which the postprocessor uses to print the glyph.
 527 .
 528 The glyph can also be input to groff using this code by means of the
 529 .B \[rs]N
 530 escape sequence.
 531 .
 532 The code can be any integer.
 533 .
 534 If it starts with a\~\c
 535 .B 0
 536 it is interpreted as octal;
 537 if it starts with
 538 .B 0x
 539 or
 540 .B 0X
 541 it is interpreted as hexadecimal.
 542 .
 543 Note, however, that the
 544 .B \[rs]N
 545 escape sequence only accepts a decimal integer.
 546 .
 547 .LP
 548 The
 549 .I entity_name
 550 field gives an ASCII string identifying the glyph which the
 551 postprocessor uses to print that glyph.
 552 .
 553 This field is optional and is currently used by
 554 .B grops
 555 to build sub-encoding arrays for PS fonts containing more than 256
 556 glyphs.
 557 .
 558 (It has also been used for
 559 .BR \%grohtml 's
 560 entity names but for efficiency reasons this data is now compiled
 561 directly into
 562 .BR \%grohtml .)
 563 .
 564 .LP
 565 Anything on the line after the encoding field or \[oq]\-\-\[cq] are
 566 ignored.
 567 .
 568 .LP
 569 The
 570 .I metrics
 571 field has the form (in one line; it is broken here for the sake of
 572 readability):
 573 .
 574 .IP
 575 .I width\/\c
 576 .RI [\fB, height\/\c
 577 .RI [\fB, depth\/\c
 578 .RI [\fB, italic-correction
 579 .br
 580 .RI [\fB, left-italic-correction\/\c
 581 .RI [\fB, subscript-correction ]]]]]
 582 .
 583 .LP
 584 There must not be any spaces between these subfields.
 585 .
 586 Missing subfields are assumed to be\~0.
 587 .
 588 The subfields are all decimal integers.
 589 .
 590 Since there is no associated binary format, these
 591 values are not required to fit into a variable of type
 592 .B char
 593 as they are in ditroff.
 594 .
 595 The
 596 .I width
 597 subfields gives the width of the glyph.
 598 .
 599 The
 600 .I height
 601 subfield gives the height of the glyph (upwards is positive);
 602 if a glyph does not extend above the baseline, it should be
 603 given a zero height, rather than a negative height.
 604 .
 605 The
 606 .I depth
 607 subfield gives the depth of the glyph, that is, the distance
 608 below the baseline to which the glyph extends (downwards is positive);
 609 if a glyph does not extend below the baseline, it should be
 610 given a zero depth, rather than a negative depth.
 611 .
 612 The
 613 .I italic-correction
 614 subfield gives the amount of space that should be added after the
 615 glyph when it is immediately to be followed by a glyph
 616 from a roman font.
 617 .
 618 The
 619 .I left-italic-correction
 620 subfield gives the amount of space that should be added before the
 621 glyph when it is immediately to be preceded by a glyph
 622 from a roman font.
 623 .
 624 The
 625 .I subscript-correction
 626 gives the amount of space that should be added after a glyph
 627 before adding a subscript.
 628 .
 629 This should be less than the italic correction.
 630 .
 631 .LP
 632 A line in the charset section can also have the format
 633 .
 634 .IP
 635 .I name \fB\[dq]
 636 .
 637 .LP
 638 This indicates that
 639 .I name
 640 is just another name for the glyph mentioned in the
 641 preceding line.
 642 .
 643 .LP
 644 The word
 645 .B kernpairs
 646 starts the kernpairs section.
 647 .
 648 This contains a sequence of lines of the form:
 649 .
 650 .IP
 651 .I c1 c2 n
 652 .
 653 .LP
 654 This means that when glyph
 655 .I c1
 656 appears next to glyph
 657 .I c2
 658 the space between them should be increased by\~\c
 659 .IR n .
 660 .
 661 Most entries in kernpairs section have a negative value for\~\c
 662 .IR n .
 663 .
 664 .
 665 .\" ====================================================================
 666 .SH FILES
 667 .\" ====================================================================
 668 .
 669 .TP
 670 .IR @FONTDIR@/dev name /DESC
 671 Device description file for device
 672 .IR name .
 673 .
 674 .TP
 675 .IR @FONTDIR@/dev name / F
 676 Font file for font\~\c
 677 .I F
 678 of device
 679 .IR name .
 680 .
 681 .
 682 .\" ====================================================================
 683 .SH "SEE ALSO"
 684 .\" ====================================================================
 685 .
 686 .BR groff_out (@MAN5EXT@),
 687 .BR @g@troff (@MAN1EXT@),
 688 .BR addftinfo (@MAN1EXT@),
 689 .BR afmtodit (@MAN1EXT@)
 690 .
 691 .
 692 .P
 693 .\" XXX: Why is this paragraph _here_, of all places?
 694 A man page
 695 .IR name ( n )
 696 of section
 697 .I n
 698 can be viewed either with
 699 .RS
 700 \[Do]
 701 .BI man " n name"
 702 .RE
 703 for text mode or
 704 .RS
 705 \[Do]
 706 .BI groffer " n name"
 707 .RE
 708 for graphical mode (default is PDF mode).
 709 .
 710 .
 711 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
 712 .cp \n[groff_font_C]
 713 .
 714 .
 715 .\" ====================================================================
 716 .\" Editor settings
 717 .\" ====================================================================
 718 .
 719 .\" Local Variables:
 720 .\" mode: nroff
 721 .\" fill-column: 72
 722 .\" End:
 723 .\" vim: set filetype=groff textwidth=72: