contrib/groff-1.19/man/groff_font.man

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