man/groff_font.man

   1 .ig \"-*- nroff -*-
   2 Copyright (C) 1989-1995 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 .de TQ
  20 .br
  21 .ns
  22 .TP \\$1
  23 ..
  24 .\" Like TP, but if specified indent is more than half
  25 .\" the current line-length - indent, use the default indent.
  26 .de Tp
  27 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
  28 .el .TP "\\$1"
  29 ..
  30 .TH GROFF_FONT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
  31 .SH NAME
  32 groff_font \- format of groff device and font description files
  33 .SH DESCRIPTION
  34 The groff font format is roughly a superset of the ditroff
  35 font format.
  36 Unlike the ditroff font format, there is no associated binary
  37 format.
  38 The font files for device
  39 .I name
  40 are stored in a directory
  41 .BI dev name.
  42 There are two types of file: a
  43 device description file called
  44 .B DESC
  45 and for each font
  46 .I F
  47 a font file called
  48 .IR F .
  49 These are text files;
  50 there is no associated binary format.
  51 .SS DESC file format
  52 The DESC file can contain the following types of line:
  53 .TP
  54 .BI res\  n
  55 There are
  56 .I n
  57 machine units per inch.
  58 .TP
  59 .BI hor\  n
  60 The horizontal resolution is
  61 .I n
  62 machine units.
  63 .TP
  64 .BI vert\  n
  65 The vertical resolution is
  66 .I n
  67 machine units.
  68 .TP
  69 .BI sizescale\  n
  70 The scale factor for pointsizes.
  71 By default this has a value of 1.
  72 One
  73 .I
  74 scaled point
  75 is equal to
  76 one
  77 .RI point/ n .
  78 The arguments to the
  79 .B unitwidth
  80 and
  81 .B sizes
  82 commands are given in scaled points.
  83 .TP
  84 .BI unitwidth\  n
  85 Quantities in the font files are given in machine units
  86 for fonts whose point size is
  87 .I n
  88 scaled points.
  89 .TP
  90 .B tcommand
  91 This means that the postprocessor can handle the
  92 .B t
  93 and
  94 .B u
  95 output commands.
  96 .TP
  97 .BI sizes\  s1\ s2\|.\|.\|.\|sn\  0
  98 This means that the device has fonts at
  99 .IR s1 ,
 100 .IR s2 ,\|.\|.\|.\| sn
 101 scaled points.
 102 The list of sizes must be terminated by a
 103 .BR 0 .
 104 Each
 105 .BI s i
 106 can also be a range of sizes
 107 .IR m \- n .
 108 The list can extend over more than one line.
 109 .TP
 110 .BI styles\  S1\ S2\|.\|.\|.\|Sm
 111 The first
 112 .I m
 113 font positions will be associated with styles
 114 .IR S1\|.\|.\|.\|Sm .
 115 .TP
 116 .BI fonts\  n\ F1\ F2\ F3\|.\|.\|.\|Fn
 117 Fonts
 118 .I F1\|.\|.\|.\|Fn
 119 will be mounted in the font positions
 120 .IR m +1,\|.\|.\|., m + n
 121 where
 122 .I m
 123 is the number of styles.
 124 This command may extend over more than one line.
 125 A font name of
 126 .B 0
 127 will cause no font to be mounted on the corresponding font position.
 128 .TP
 129 .BI family\  fam
 130 The default font family is
 131 .IR fam .
 132 .TP
 133 .B use_charnames_in_special
 134 This command indicates that troff should encode named characters inside
 135 special commands.
 136 .TP
 137 .B pass_filenames
 138 requests that troff tells the driver the source file name being processed.
 139 This is achieved by another tcommand:
 140 .B F
 141 .IR filename .
 142 .TP
 143 .B charset
 144 This line and everything following in the file are ignored.
 145 It is allowed for the sake of backwards compatibility.
 146 .LP
 147 The res, unitwidth, fonts and sizes lines are compulsory.
 148 Other commands are ignored by
 149 .B troff
 150 but may be used by postprocessors to store arbitrary information
 151 about the device in the DESC file.
 152 .SS Font file format
 153 A font file has two sections. The first section is a sequence
 154 of lines each containing a sequence of blank delimited
 155 words; the first word in the line is a key, and subsequent
 156 words give a value for that key.
 157 .TP
 158 .BI name\  F
 159 The name of the font is
 160 .IR F .
 161 .TP
 162 .BI spacewidth\  n
 163 The normal width of a space is
 164 .IR n .
 165 .TP
 166 .BI slant\  n
 167 The characters of the font have a slant of
 168 .I n
 169 degrees. (Positive means forward.)
 170 .TP
 171 .BI ligatures\  lig1\ lig2\|.\|.\|.\|lign\ \fR[ 0 \fR]
 172 Characters
 173 .IR lig1 ,
 174 .IR lig2 ,\|.\|.\|., lign
 175 are ligatures; possible ligatures are
 176 .BR ff ,
 177 .BR fi ,
 178 .BR fl
 179 and
 180 .BR ffl .
 181 For backwards compatibility, the list of ligatures may be terminated
 182 with a
 183 .BR 0.
 184 The list of ligatures may not extend over more than one line.
 185 .TP
 186 .B special
 187 The font is
 188 .IR special ;
 189 this means that when a character is requested that is not present in
 190 the current font, it will be searched for in any special fonts that
 191 are mounted.
 192 .LP
 193 Other commands are ignored by
 194 .B troff
 195 but may be used by postprocessors to store arbitrary information
 196 about the font in the font file.
 197 .LP
 198 The first section can contain comments which start with the
 199 .B #
 200 character and extend to the end of a line.
 201 .LP
 202 The second section contains one or two subsections.
 203 It must contain a
 204 .I charset
 205 subsection
 206 and it may also contain a
 207 .I kernpairs
 208 subsection.
 209 These subsections can appear in any order.
 210 Each subsection starts with a word on a line by itself.
 211 .LP
 212 The word
 213 .B charset
 214 starts the charset subsection.
 215 The
 216 .B charset
 217 line is followed by a sequence of lines.
 218 Each line gives information for one character.
 219 A line comprises a number of fields separated
 220 by blanks or tabs. The format is
 221 .IP
 222 .I name metrics type code
 223 .RI [ entity_name ]
 224 .RB [ --
 225 .IR comment ]
 226 .LP
 227 .I name
 228 identifies the character:
 229 if
 230 .I name
 231 is a single character
 232 .I c
 233 then it corresponds to the groff input character
 234 .IR c ;
 235 if it is of the form
 236 .BI \e c
 237 where c is a single character, then it
 238 corresponds to the groff input character
 239 .BI \e c\fR;
 240 otherwise it corresponds to the groff input character
 241 .BI \e[ name ]
 242 (if it is exactly two characters
 243 .I xx
 244 it can be entered as
 245 .BI \e( xx\fR.)
 246 Groff supports eight bit characters; however some utilities
 247 has difficulties with eight bit characters.
 248 For this reason, there is a convention that the name
 249 .BI char n
 250 is equivalent to the single character whose code is
 251 .I n .
 252 For example,
 253 .B char163
 254 would be equivalent to the character with code 163
 255 which is the pounds sterling sign in ISO Latin-1.
 256 The name
 257 .B \-\-\-
 258 is special and indicates that the character is unnamed;
 259 such characters can only be used by means of the
 260 .B \eN
 261 escape sequence in
 262 .BR troff .
 263 .LP
 264 The
 265 .I type
 266 field gives the character type:
 267 .TP
 268 1
 269 means the character has an descender, for example, p;
 270 .TP
 271 2
 272 means the character has an ascender, for example, b;
 273 .TP
 274 3
 275 means the character has both an ascender and a descender, for example,
 276 (.
 277 .LP
 278 The
 279 .I code
 280 field gives the code which the postprocessor uses to print the character.
 281 The character can also be input to groff using this code by means of the
 282 .B \eN
 283 escape sequence.
 284 The code can be any integer.
 285 If it starts with a
 286 .B 0
 287 it will be interpreted as octal;
 288 if it starts with
 289 .B 0x
 290 or
 291 .B 0X
 292 it will be intepreted as hexadecimal.
 293 .LP
 294 The
 295 .I entity_name
 296 field gives an ascii string identifying the glyph which the postprocessor
 297 uses to print the character.
 298 This field is optional and has been introduced so that the html device driver
 299 can encode its character set.
 300 For example, the character `\e[Po]' is represented as `&pound;' in html 4.0.
 301 .LP
 302 Anything on the line after the encoding field resp. after `-\&-' will
 303 be ignored.
 304 .LP
 305 The
 306 .I metrics
 307 field has the form:
 308 .IP
 309 .IR width [\fB, height [\fB, depth [\fB, italic_correction [\fB, \
 310 left_italic_correction [\fB, subscript_correction ]]]]]
 311 .LP
 312 There must not be any spaces between these subfields.
 313 Missing subfields are assumed to be 0.
 314 The subfields are all decimal integers.
 315 Since there is no associated binary format, these
 316 values are not required to fit into a variable of type
 317 .B char
 318 as they are in ditroff.
 319 The
 320 .I width
 321 subfields gives the width of the character.
 322 The
 323 .I height
 324 subfield gives the height of the character (upwards is positive);
 325 if a character does not extend above the baseline, it should be
 326 given a zero height, rather than a negative height.
 327 The
 328 .I depth
 329 subfield gives the depth of the character, that is, the distance
 330 below the lowest point below the baseline to which the
 331 character extends (downwards is positive);
 332 if a character does not extend below above the baseline, it should be
 333 given a zero depth, rather than a negative depth.
 334 The
 335 .I italic_correction
 336 subfield gives the amount of space that should be added after the
 337 character when it is immediately to be followed by a character
 338 from a roman font.
 339 The
 340 .I left_italic_correction
 341 subfield gives the amount of space that should be added before the
 342 character when it is immediately to be preceded by a character
 343 from a roman font.
 344 The
 345 .I subscript_correction
 346 gives the amount of space that should be added after a character
 347 before adding a subscript.
 348 This should be less than the italic correction.
 349 .LP
 350 A line in the charset section can also have the format
 351 .IP
 352 .I
 353 name \fB"
 354 .LP
 355 This indicates that
 356 .I name
 357 is just another name for the character mentioned in the
 358 preceding line.
 359 .LP
 360 The word
 361 .B kernpairs
 362 starts the kernpairs section.
 363 This contains a sequence of lines of the form:
 364 .IP
 365 .I
 366 c1 c2 n
 367 .LP
 368 This means that when character
 369 .I c1
 370 appears next to character
 371 .I c2
 372 the space between them should be increased by
 373 .IR n .
 374 Most entries in kernpairs section will have a negative value for
 375 .IR n .
 376 .SH FILES
 377 .Tp \w'@FONTDIR@/devname/DESC'u+3n
 378 .BI @FONTDIR@/dev name /DESC
 379 Device description file for device
 380 .IR name .
 381 .TP
 382 .BI @FONTDIR@/dev name / F
 383 Font file for font
 384 .I F
 385 of device
 386 .IR name .
 387 .SH "SEE ALSO"
 388 .BR groff_out (@MAN5EXT@),
 389 .BR @g@troff (@MAN1EXT@).