man/groff_font.man

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