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