contrib/groff/man/groff_font.man

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