179543Sru.ig 2151497SruCopyright (C) 1989-1995, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. 318099Spst 418099SpstPermission is granted to make and distribute verbatim copies of 518099Spstthis manual provided the copyright notice and this permission notice 618099Spstare preserved on all copies. 718099Spst 818099SpstPermission is granted to copy and distribute modified versions of this 918099Spstmanual under the conditions for verbatim copying, provided that the 1018099Spstentire resulting derived work is distributed under the terms of a 1118099Spstpermission notice identical to this one. 1218099Spst 1318099SpstPermission is granted to copy and distribute translations of this 1418099Spstmanual into another language, under the above conditions for modified 1518099Spstversions, except that this permission notice may be included in 1618099Spsttranslations approved by the Free Software Foundation instead of in 1718099Spstthe original English. 1818099Spst.. 19104862Sru. 20151497Sru.do nr groff_font_C \n[.C] 21151497Sru.cp 0 22151497Sru. 2318099Spst.de TQ 24151497Sru. br 25151497Sru. ns 26151497Sru. TP \\$1 2718099Spst.. 28104862Sru. 2918099Spst.\" Like TP, but if specified indent is more than half 3018099Spst.\" the current line-length - indent, use the default indent. 3118099Spst.de Tp 32151497Sru. ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP 33151497Sru. el .TP "\\$1" 3418099Spst.. 35104862Sru. 36104862Sru. 3718099Spst.TH GROFF_FONT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@" 38104862Sru. 39104862Sru. 4018099Spst.SH NAME 4118099Spstgroff_font \- format of groff device and font description files 42104862Sru. 43104862Sru. 4418099Spst.SH DESCRIPTION 4518099SpstThe groff font format is roughly a superset of the ditroff 4618099Spstfont format. 47104862Sru. 4818099SpstThe font files for device 4918099Spst.I name 5018099Spstare stored in a directory 51151497Sru.BI dev name\c 52151497Sru\&. 53104862Sru. 5418099SpstThere are two types of file: a 5518099Spstdevice description file called 5618099Spst.B DESC 5718099Spstand for each font 5818099Spst.I F 5918099Spsta font file called 6018099Spst.IR F . 61104862Sru. 6218099SpstThese are text files; 63104862Sruunlike the ditroff font format, 6418099Spstthere is no associated binary format. 65104862Sru. 66104862Sru. 6718099Spst.SS DESC file format 68104862Sru. 69104862SruThe DESC file can contain the following types of line as shown below. 70104862Sru. 71104862SruLater entries in the file override previous values. 72104862Sru. 7318099Spst.TP 74104862Sru.B charset 75104862SruThis line and everything following in the file are ignored. 76104862Sru. 77104862SruIt is allowed for the sake of backwards compatibility. 78104862Sru. 7918099Spst.TP 80104862Sru.BI family\ fam 81104862SruThe default font family is 82104862Sru.IR fam . 83104862Sru. 84104862Sru.TP 85104862Sru.BI fonts\ n\ F1\ F2\ F3\|.\|.\|.\|Fn 86104862SruFonts 87104862Sru.I F1\|.\|.\|.\|Fn 88104862Sruwill be mounted in the font positions 89104862Sru.IR m +1,\|.\|.\|., m + n 90104862Sruwhere 91104862Sru.I m 92104862Sruis the number of styles. 93104862Sru. 94104862SruThis command may extend over more than one line. 95104862Sru. 96104862SruA font name of 97104862Sru.B 0 98104862Sruwill cause no font to be mounted on the corresponding font position. 99104862Sru. 100104862Sru.TP 10118099Spst.BI hor\ n 10218099SpstThe horizontal resolution is 10318099Spst.I n 10418099Spstmachine units. 105104862Sru. 10618099Spst.TP 107151497Sru.BI image_generator\ string 108151497SruNeeded for 109151497Sru.B grohtml 110151497Sruonly. 111151497SruIt specifies the program to generate PNG images from 112151497SruPostScript input. 113151497SruUnder GNU/Linux this is usually 114151497Sru.I gs 115151497Srubut under other systems (notably cygwin) it might be set to another name. 116151497Sru. 117151497Sru.TP 118151497Sru.BI paperlength\ n 119104862SruThe physical vertical dimension of the output medium in machine units. 120104862Sru. 121104862SruThis isn't used by 122104862Sru.B troff 123114402Sruitself but by output devices. 124104862Sru. 125114402SruDeprecated. 126104862Sru. 127114402SruUse 128114402Sru.B papersize 129114402Sruinstead. 130104862Sru. 131104862Sru.TP 132104862Sru.BI papersize\ string 133104862SruSelect a paper size. 134104862Sru. 135104862SruValid values for 136104862Sru.I string 137104862Sruare the ISO paper types A0-A7, B0-B7, C0-C7, D0-D7, DL, and the US paper 138104862Srutypes letter, legal, tabloid, ledger, statement, executive, com10, and 139104862Srumonarch. 140104862Sru. 141104862SruCase is not significant for 142104862Sru.IR string 143104862Sruif it holds predefined paper types. 144104862Sru. 145104862SruAlternatively, 146104862Sru.I string 147104862Srucan be a file name (e.g.\& `/etc/papersize'); if the file can be opened, 148104862Sru.B groff 149104862Srureads the first line and tests for the above paper sizes. 150104862Sru. 151104862SruFinally, 152104862Sru.I string 153104862Srucan be a custom paper size in the format 154104862Sru.IB length , width 155104862Sru(no spaces before and after the comma). 156104862Sru. 157104862SruBoth 158104862Sru.I length 15918099Spstand 160104862Sru.I width 161104862Srumust have a unit appended; valid values are `i' for inches, `c' for 162104862Srucentimeters, `p' for points, and `P' for picas. 163104862Sru. 164104862SruExample: 165104862Sru.BR 12c,235p . 166104862Sru. 167104862SruAn argument which starts with a digit is always treated as a custom paper 168104862Sruformat. 169104862Sru. 170104862Sru.B papersize 171104862Srusets both the vertical and horizontal dimension of the output medium. 172104862Sru. 173104862Sru.IP 174104862SruMore than one argument can be specified; 175104862Sru.B groff 176104862Sruscans from left to right and uses the first valid paper specification. 177104862Sru. 178114402Sru.TP 179114402Sru.BI paperwidth\ n 180114402SruThe physical horizontal dimension of the output medium in machine units. 181104862Sru. 182114402SruDeprecated. 183114402Sru. 184114402SruUse 185114402Sru.B papersize 186114402Sruinstead. 187114402Sru. 188114402SruThis isn't used by 189114402Sru.BR troff 190114402Sruitself but by output devices. 191114402Sru. 19218099Spst.TP 193104862Sru.B pass_filenames 194104862SruMake troff tell the driver the source file name being processed. 195104862Sru. 196104862SruThis is achieved by another tcommand: 197104862Sru.B F 198104862Sru.IR filename . 199104862Sru. 20018099Spst.TP 201104862Sru.BI postpro\ program 202104862SruUse 203104862Sru.I program 204104862Sruas the postprocessor. 205104862Sru. 206104862Sru.TP 20775584Sru.BI prepro\ program 20875584SruCall 20975584Sru.I program 21075584Sruas a preprocessor. 211104862Sru. 21275584Sru.TP 213104862Sru.BI print\ program 21475584SruUse 21575584Sru.I program 216104862Sruas the spooler program for printing. 217104862Sru. 218104862SruIf omitted, the 219104862Sru.B \-l 22018099Spstand 221104862Sru.B \-L 222104862Sruoptions of 223104862Sru.B groff 224104862Sruare ignored. 225104862Sru. 22618099Spst.TP 227104862Sru.BI res\ n 228104862SruThere are 229104862Sru.I n 230104862Srumachine units per inch. 231104862Sru. 232104862Sru.TP 23318099Spst.BI sizes\ s1\ s2\|.\|.\|.\|sn\ 0 23418099SpstThis means that the device has fonts at 23518099Spst.IR s1 , 23618099Spst.IR s2 ,\|.\|.\|.\| sn 23718099Spstscaled points. 238104862Sru. 23918099SpstThe list of sizes must be terminated by a 24018099Spst.BR 0 . 241104862Sru. 24218099SpstEach 243104862Sru.I si 24418099Spstcan also be a range of sizes 24518099Spst.IR m \- n . 246104862Sru. 24718099SpstThe list can extend over more than one line. 248104862Sru. 24918099Spst.TP 250104862Sru.BI sizescale\ n 251104862SruThe scale factor for pointsizes. 252104862Sru. 253104862SruBy default this has a value of 1. 254104862Sru. 255104862SruOne 256104862Sru.I 257104862Sruscaled point 258104862Sruis equal to 259104862Sruone 260104862Sru.RI point/ n . 261104862Sru. 262104862SruThe arguments to the 263104862Sru.B unitwidth 264104862Sruand 265104862Sru.B sizes 266104862Srucommands are given in scaled points. 267104862Sru. 268104862Sru.TP 26918099Spst.BI styles\ S1\ S2\|.\|.\|.\|Sm 27018099SpstThe first 27118099Spst.I m 27218099Spstfont positions will be associated with styles 27318099Spst.IR S1\|.\|.\|.\|Sm . 274104862Sru. 27518099Spst.TP 276104862Sru.B tcommand 277104862SruThis means that the postprocessor can handle the 278104862Sru.B t 279104862Sruand 280104862Sru.B u 281104862Sruoutput commands. 282104862Sru. 28318099Spst.TP 284104862Sru.BI unitwidth\ n 285104862SruQuantities in the font files are given in machine units 286104862Srufor fonts whose point size is 287104862Sru.I n 288104862Sruscaled points. 289104862Sru. 29018099Spst.TP 291151497Sru.B unscaled_charwidths 292151497SruMake the font handling module always return unscaled character widths. 293151497SruNeeded for the 294151497Sru.B grohtml 295151497Srudevice. 296151497Sru. 297151497Sru.TP 29869626Sru.B use_charnames_in_special 29969626SruThis command indicates that troff should encode named characters inside 30069626Sruspecial commands. 301104862Sru. 30269626Sru.TP 303104862Sru.BI vert\ n 304104862SruThe vertical resolution is 305104862Sru.I n 306104862Srumachine units. 307104862Sru. 308104862Sru.LP 309104862SruThe 310104862Sru.BR res , 311104862Sru.BR unitwidth , 312104862Sru.BR fonts , 31375584Sruand 314104862Sru.B sizes 315104862Srulines are compulsory. 316104862Sru. 317114402SruNot all commands in the DESC file are used by 31818099Spst.B troff 319114402Sruitself; some of the keywords (or even additional ones) are used by 320114402Srupostprocessors to store arbitrary information about the device. 321104862Sru. 32269626Sru.LP 32369626SruHere a list of obsolete keywords which are recognized by 32469626Sru.B groff 32569626Srubut completely ignored: 32669626Sru.BR spare1 , 32769626Sru.BR spare2 , 32869626Sru.BR biggestfont . 329104862Sru. 330104862Sru. 33118099Spst.SS Font file format 332104862Sru. 333104862SruA font file has two sections. 334104862SruThe first section is a sequence 33518099Spstof lines each containing a sequence of blank delimited 33618099Spstwords; the first word in the line is a key, and subsequent 33718099Spstwords give a value for that key. 338104862Sru. 33918099Spst.TP 34018099Spst.BI ligatures\ lig1\ lig2\|.\|.\|.\|lign\ \fR[ 0 \fR] 34118099SpstCharacters 34218099Spst.IR lig1 , 343104862Sru.IR lig2 ,\ \|.\|.\|.,\ lign 34418099Spstare ligatures; possible ligatures are 34518099Spst.BR ff , 34618099Spst.BR fi , 34769626Sru.BR fl , 34869626Sru.B ffi 34918099Spstand 35018099Spst.BR ffl . 351104862Sru. 35218099SpstFor backwards compatibility, the list of ligatures may be terminated 35318099Spstwith a 35418099Spst.BR 0. 355104862Sru. 35618099SpstThe list of ligatures may not extend over more than one line. 357104862Sru. 35818099Spst.TP 359104862Sru.BI name\ F 360104862SruThe name of the font is 361104862Sru.IR F . 362104862Sru. 363104862Sru.TP 364104862Sru.BI slant\ n 365104862SruThe characters of the font have a slant of 366104862Sru.I n 367104862Srudegrees. 368104862Sru. 369104862Sru(Positive means forward.) 370104862Sru. 371104862Sru.TP 372104862Sru.BI spacewidth\ n 373104862SruThe normal width of a space is 374104862Sru.IR n . 375104862Sru. 376104862Sru.TP 37718099Spst.B special 37818099SpstThe font is 37918099Spst.IR special ; 38018099Spstthis means that when a character is requested that is not present in 38118099Spstthe current font, it will be searched for in any special fonts that 38218099Spstare mounted. 383104862Sru. 38418099Spst.LP 38518099SpstOther commands are ignored by 38618099Spst.B troff 38718099Spstbut may be used by postprocessors to store arbitrary information 38818099Spstabout the font in the font file. 389104862Sru. 39018099Spst.LP 39118099SpstThe first section can contain comments which start with the 39218099Spst.B # 39318099Spstcharacter and extend to the end of a line. 394104862Sru. 39518099Spst.LP 39618099SpstThe second section contains one or two subsections. 397104862Sru. 39818099SpstIt must contain a 39918099Spst.I charset 40018099Spstsubsection 40118099Spstand it may also contain a 40218099Spst.I kernpairs 40318099Spstsubsection. 404104862Sru. 40518099SpstThese subsections can appear in any order. 406104862Sru. 40718099SpstEach subsection starts with a word on a line by itself. 408104862Sru. 40918099Spst.LP 41018099SpstThe word 41118099Spst.B charset 41218099Spststarts the charset subsection. 413104862Sru. 41418099SpstThe 41518099Spst.B charset 41618099Spstline is followed by a sequence of lines. 417104862Sru. 41818099SpstEach line gives information for one character. 419104862Sru. 42018099SpstA line comprises a number of fields separated 421104862Sruby blanks or tabs. 422104862Sru. 423104862SruThe format is 424104862Sru. 42518099Spst.IP 42669626Sru.I name metrics type code 42769626Sru.RI [ entity_name ] 42869626Sru.RB [ -- 42969626Sru.IR comment ] 430104862Sru. 43118099Spst.LP 43218099Spst.I name 43318099Spstidentifies the character: 43418099Spstif 43518099Spst.I name 43618099Spstis a single character 43718099Spst.I c 43818099Spstthen it corresponds to the groff input character 43918099Spst.IR c ; 44018099Spstif it is of the form 441104862Sru.BI \[rs] c 44218099Spstwhere c is a single character, then it 443104862Srucorresponds to the special character 444104862Sru.BI \[rs][ c ]\fR; 44518099Spstotherwise it corresponds to the groff input character 446104862Sru.BI \[rs][ name ]\fR. 447104862Sru. 448104862SruIf it is exactly two characters 44918099Spst.I xx 45018099Spstit can be entered as 451104862Sru.BI \[rs]( xx\fR. 452104862Sru. 453104862SruNote that single-letter special characters can't be accessed as 454104862Sru.BI \[rs] c\fR; 455104862Sruthe only exception is `\[rs]-' which is identical to `\[rs][-]'. 456104862Sru. 457104862SruThe name 458104862Sru.B \-\-\- 459104862Sruis special and indicates that the character is unnamed; 460104862Srusuch characters can only be used by means of the 461104862Sru.B \[rs]N 462104862Sruescape sequence in 463104862Sru.BR troff . 464104862Sru. 465104862Sru.LP 466104862SruGroff supports eight-bit characters; however some utilities 467104862Sruhave difficulties with eight-bit characters. 468104862Sru. 46918099SpstFor this reason, there is a convention that the name 47018099Spst.BI char n 47118099Spstis equivalent to the single character whose code is 472104862Sru.IR n . 473104862Sru. 47418099SpstFor example, 47518099Spst.B char163 47618099Spstwould be equivalent to the character with code 163 47718099Spstwhich is the pounds sterling sign in ISO Latin-1. 478104862Sru. 47918099Spst.LP 48018099SpstThe 48118099Spst.I type 48218099Spstfield gives the character type: 483104862Sru. 48418099Spst.TP 48518099Spst1 486104862Srumeans the character has a descender, for example, p; 487104862Sru. 48818099Spst.TP 48918099Spst2 49018099Spstmeans the character has an ascender, for example, b; 491104862Sru. 49218099Spst.TP 49318099Spst3 49418099Spstmeans the character has both an ascender and a descender, for example, 49518099Spst(. 496104862Sru. 49718099Spst.LP 49818099SpstThe 49918099Spst.I code 50018099Spstfield gives the code which the postprocessor uses to print the character. 501104862Sru. 50218099SpstThe character can also be input to groff using this code by means of the 503104862Sru.B \[rs]N 50418099Spstescape sequence. 505104862Sru. 50618099SpstThe code can be any integer. 507104862Sru. 50818099SpstIf it starts with a 50918099Spst.B 0 51018099Spstit will be interpreted as octal; 51118099Spstif it starts with 51218099Spst.B 0x 51318099Spstor 51418099Spst.B 0X 51518099Spstit will be intepreted as hexadecimal. 516104862Sru. 517104862SruNote, however, that the 518104862Sru.B \[rs]N 519104862Sruescape sequence only accepts a decimal integer. 520104862Sru. 52118099Spst.LP 52269626SruThe 52369626Sru.I entity_name 52469626Srufield gives an ascii string identifying the glyph which the postprocessor 52569626Sruuses to print the character. 526104862Sru. 52769626SruThis field is optional and has been introduced so that the html device driver 52869626Srucan encode its character set. 529104862Sru. 530104862SruFor example, the character `\[rs][Po]' is represented as `£' in 531104862Sruhtml\~4.0. 532104862Sru. 53318099Spst.LP 53469626SruAnything on the line after the encoding field resp. after `-\&-' will 53569626Srube ignored. 536104862Sru. 53769626Sru.LP 53818099SpstThe 53918099Spst.I metrics 540104862Srufield has the form (in one line; it is broken here for the sake of 541104862Srureadability): 542104862Sru. 54318099Spst.IP 544151497Sru.I width\c 545151497Sru.RI [\fB, height\c 546151497Sru.RI [\fB, depth\c 547151497Sru.RI [\fB, italic-correction 548104862Sru.br 549151497Sru.RI [\fB, left-italic-correction\c 550151497Sru.RI [\fB, subscript-correction ]]]]] 551104862Sru. 55218099Spst.LP 55318099SpstThere must not be any spaces between these subfields. 554104862Sru. 55518099SpstMissing subfields are assumed to be 0. 556104862Sru. 55718099SpstThe subfields are all decimal integers. 558104862Sru. 55918099SpstSince there is no associated binary format, these 56018099Spstvalues are not required to fit into a variable of type 56118099Spst.B char 56218099Spstas they are in ditroff. 563104862Sru. 56418099SpstThe 56518099Spst.I width 56618099Spstsubfields gives the width of the character. 567104862Sru. 56818099SpstThe 56918099Spst.I height 57018099Spstsubfield gives the height of the character (upwards is positive); 57118099Spstif a character does not extend above the baseline, it should be 57218099Spstgiven a zero height, rather than a negative height. 573104862Sru. 57418099SpstThe 57518099Spst.I depth 57618099Spstsubfield gives the depth of the character, that is, the distance 57718099Spstbelow the lowest point below the baseline to which the 57818099Spstcharacter extends (downwards is positive); 57918099Spstif a character does not extend below above the baseline, it should be 58018099Spstgiven a zero depth, rather than a negative depth. 581104862Sru. 58218099SpstThe 583104862Sru.I italic-correction 58418099Spstsubfield gives the amount of space that should be added after the 58518099Spstcharacter when it is immediately to be followed by a character 58618099Spstfrom a roman font. 587104862Sru. 58818099SpstThe 589104862Sru.I left-italic-correction 59018099Spstsubfield gives the amount of space that should be added before the 59118099Spstcharacter when it is immediately to be preceded by a character 59218099Spstfrom a roman font. 593104862Sru. 59418099SpstThe 595104862Sru.I subscript-correction 59618099Spstgives the amount of space that should be added after a character 59718099Spstbefore adding a subscript. 598104862Sru. 59918099SpstThis should be less than the italic correction. 600104862Sru. 60118099Spst.LP 60218099SpstA line in the charset section can also have the format 603104862Sru. 60418099Spst.IP 60518099Spst.I 60618099Spstname \fB" 607104862Sru. 60818099Spst.LP 60918099SpstThis indicates that 61018099Spst.I name 61118099Spstis just another name for the character mentioned in the 61218099Spstpreceding line. 613104862Sru. 61418099Spst.LP 61518099SpstThe word 61618099Spst.B kernpairs 61718099Spststarts the kernpairs section. 618104862Sru. 61918099SpstThis contains a sequence of lines of the form: 620104862Sru. 62118099Spst.IP 622104862Sru.I c1 c2 n 623104862Sru. 62418099Spst.LP 62518099SpstThis means that when character 62618099Spst.I c1 62718099Spstappears next to character 62818099Spst.I c2 62918099Spstthe space between them should be increased by 63018099Spst.IR n . 631104862Sru. 63218099SpstMost entries in kernpairs section will have a negative value for 63318099Spst.IR n . 634104862Sru. 635104862Sru. 63618099Spst.SH FILES 637104862Sru. 63818099Spst.Tp \w'@FONTDIR@/devname/DESC'u+3n 63918099Spst.BI @FONTDIR@/dev name /DESC 64018099SpstDevice description file for device 64118099Spst.IR name . 642104862Sru. 64318099Spst.TP 64418099Spst.BI @FONTDIR@/dev name / F 64518099SpstFont file for font 64618099Spst.I F 64718099Spstof device 64818099Spst.IR name . 649104862Sru. 650104862Sru. 65118099Spst.SH "SEE ALSO" 652104862Sru. 65318099Spst.BR groff_out (@MAN5EXT@), 65418099Spst.BR @g@troff (@MAN1EXT@). 65579543Sru. 656151497Sru.cp \n[groff_font_C] 657151497Sru. 65879543Sru.\" Local Variables: 65979543Sru.\" mode: nroff 66079543Sru.\" End: 661