contrib/groff/man/groff_font.man

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