src/utils/afmtodit/afmtodit.man

   1 .TH AFMTODIT @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   2 .SH NAME
   3 afmtodit \- create font files for use with groff \-Tps and \-Tpdf
   4 .
   5 .
   6 .\" --------------------------------------------------------------------
   7 .\" Leagal Terms
   8 .
   9 .de co
  10 Copyright \[co] 1989-2014 Free Software Foundation, Inc.
  11
  12 Permission is granted to make and distribute verbatim copies of
  13 this manual provided the copyright notice and this permission notice
  14 are preserved on all copies.
  15
  16 Permission is granted to copy and distribute modified versions of this
  17 manual under the conditions for verbatim copying, provided that the
  18 entire resulting derived work is distributed under the terms of a
  19 permission notice identical to this one.
  20
  21 Permission is granted to copy and distribute translations of this
  22 manual into another language, under the above conditions for modified
  23 versions, except that this permission notice may be included in
  24 translations approved by the Free Software Foundation instead of in
  25 the original English.
  26 ..
  27 .
  28 .\" --------------------------------------------------------------------
  29 .\" Definitions
  30 .
  31 .\" Like TP, but if specified indent is more than half
  32 .\" the current line-length - indent, use the default indent.
  33 .de Tp
  34 .  ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
  35 .  el .TP "\\$1"
  36 ..
  37 .
  38 .de OP
  39 .  ie \\n(.$-1 .RI "[\ \fB\\$1\fP\ " "\\$2" "\ ]"
  40 .  el .RB "[\ " "\\$1" "\ ]"
  41 ..
  42 .
  43 .\" --------------------------------------------------------------------
  44 .SH SYNOPSIS
  45 .\" --------------------------------------------------------------------
  46 .
  47 .nr a \n(.j
  48 .ad l
  49 .nr i \n(.i
  50 .in +\w'\fBafmtodit 'u
  51 .ti \niu
  52 .B afmtodit
  53 .OP \-ckmnsvx
  54 .OP \-a n
  55 .OP \-d desc_file
  56 .OP \-e enc_file
  57 .OP \-f internal_name
  58 .OP \-i n
  59 .OP \-o out_file
  60 .I afm_file
  61 .I map_file
  62 .I font
  63 .br
  64 .ad \na
  65 .
  66 .
  67 .LP
  68 The whitespace between a command line option and its argument is optional.
  69 .
  70 .
  71 .\" --------------------------------------------------------------------
  72 .SH DESCRIPTION
  73 .\" --------------------------------------------------------------------
  74 .
  75 .B afmtodit
  76 creates a font file for use with groff,
  77 .BR grops ,
  78 and
  79 .BR gropdf .
  80 .
  81 .B afmtodit
  82 is written in perl;
  83 you must have perl version 5.004 or newer installed in order to run
  84 .BR afmtodit .
  85 .
  86 .
  87 .LP
  88 .I afm_file
  89 is the AFM (Adobe Font Metric) file for the font.
  90 .
  91 .
  92 .LP
  93 .I map_file
  94 is a file that says which groff character names map onto
  95 each PostScript character name;
  96 this file should contain a sequence of lines of the form
  97 .IP
  98 .I
  99 ps_char groff_char
 100 .LP
 101 where
 102 .I ps_char
 103 is the PostScript name of the character and
 104 .I groff_char
 105 is the groff name of the character (as used in the groff font file).
 106 .
 107 The same
 108 .I ps_char
 109 can occur multiple times in the file;
 110 each
 111 .I groff_char
 112 must occur at most once.
 113 .
 114 Lines starting with
 115 .B #
 116 and blank lines are ignored.
 117 .
 118 If the file isn\[aq]t found in the current directory, it is searched
 119 in the \[oq]devps/generate\[cq] subdirectory of the default font
 120 directory.
 121 .
 122 .
 123 .LP
 124 If a PostScript character is not mentioned in
 125 .IR map_file ,
 126 and a generic groff glyph name can't be deduced using the Adobe Glyph
 127 List (AGL, built into
 128 .BR afmtodit ),
 129 then
 130 .B afmtodit
 131 puts the PostScript character into the groff font file as an unnamed
 132 character which can only be accessed by the
 133 .B \eN
 134 escape sequence in
 135 .BR troff .
 136 .
 137 In particular, this is true for glyph variants like \[oq]foo.bar\[cq];
 138 all glyph names containing one or more periods are mapped to unnamed
 139 entities.
 140 .
 141 If option
 142 .B \-e
 143 is not specified, the encoding defined in the AFM file (i.e., entries
 144 with non-negative character codes) is used.
 145 .
 146 Please refer to section \[oq]Using Symbols\[cq] in the groff info file
 147 which describes how groff glyph names are constructed.
 148 .
 149 .
 150 .LP
 151 Characters not encoded in the AFM file (i.e., entries which have \-1
 152 as the character code) are still available in groff; they get glyph
 153 index values greater than 255 (or greater than the biggest character
 154 code used in the AFM file in the unlikely case that it is greater than
 155 255) in the groff font file.
 156 .
 157 Glyph indices of unencoded characters don\[aq]t have a specific order;
 158 it is best to access them with glyph names only.
 159 .
 160 .
 161 .LP
 162 The groff font file will be output to a file called
 163 .IR font ,
 164 unless the
 165 .B \-o
 166 option is used.
 167 .
 168 .
 169 .LP
 170 If there is a downloadable font file for the font, it may be listed in
 171 the file
 172 .BR @FONTDIR@/devps/download ;
 173 see
 174 .BR grops (@MAN1EXT@).
 175 .
 176 .
 177 .LP
 178 If the
 179 .B \-i
 180 option is used,
 181 .B afmtodit
 182 will automatically generate an italic correction,
 183 a left italic correction and a subscript correction
 184 for each character
 185 (the significance of these parameters is explained in
 186 .BR groff_font (@MAN5EXT@));
 187 these parameters may be specified for individual characters by
 188 adding to the
 189 .I afm_file
 190 lines of the form:
 191 .IP
 192 .BI italicCorrection\  ps_char\ n
 193 .br
 194 .BI leftItalicCorrection\  ps_char\ n
 195 .br
 196 .BI subscriptCorrection\  ps_char\ n
 197 .LP
 198 where
 199 .I ps_char
 200 is the PostScript name of the character,
 201 and
 202 .I n
 203 is the desired value of the corresponding parameter in thousandths of an em.
 204 .
 205 These parameters are normally needed only for italic (or oblique) fonts.
 206 .
 207 .
 208 .\" --------------------------------------------------------------------
 209 .SH OPTIONS
 210 .\" --------------------------------------------------------------------
 211 .
 212 .TP
 213 .BI \-a n
 214 Use
 215 .I n
 216 as the slant parameter in the font file;
 217 this is used by groff in the positioning of accents.
 218 .
 219 By default
 220 .B afmtodit
 221 uses the negative of the ItalicAngle specified in the afm file;
 222 with true italic fonts it is sometimes desirable to use
 223 a slant that is less than this.
 224 .
 225 If you find that characters from an italic font have accents
 226 placed too far to the right over them,
 227 then use the
 228 .B \-a
 229 option to give the font a smaller slant.
 230 .
 231 .TP
 232 .B \-c
 233 Include comments in the font file in order to identify the PS font.
 234 .
 235 .TP
 236 .BI \-d desc_file
 237 The device description file is
 238 .I desc_file
 239 rather than the default
 240 .BR DESC .
 241 .
 242 If not found in the current directory, the \[oq]devps\[qc]
 243 subdirectory of the default font directory is searched (this is true
 244 for both the default device description file and a file given with
 245 option
 246 .BR \-d ).
 247 .
 248 .TP
 249 .BI \-e enc_file
 250 The PostScript font should be reencoded to use the encoding described
 251 in enc_file.
 252 .
 253 The format of
 254 .I enc_file
 255 is described in
 256 .BR grops (@MAN1EXT@).
 257 .
 258 If not found in the current directory, the \[oq]devps\[cq]
 259 subdirectory of the default font directory is searched.
 260 .
 261 .TP
 262 .BI \-f name
 263 The internal name of the groff font is set to
 264 .IR name .
 265 .
 266 .TP
 267 .BI \-i n
 268 Generate an italic correction for each character so that the
 269 character's width plus the character's italic correction is equal to
 270 .I n
 271 thousandths of an em
 272 plus the amount by which the right edge of the character's bounding box
 273 is to the right of the character\[aq]s origin.
 274 .
 275 If this would result in a negative italic correction, use a zero
 276 italic correction instead.
 277 .
 278 .IP
 279 Also generate a subscript correction equal to the
 280 product of the tangent of the slant of the font and
 281 four fifths of the x-height of the font.
 282 .
 283 If this would result in a subscript correction greater than the italic
 284 correction, use a subscript correction equal to the italic correction
 285 instead.
 286 .
 287 .IP
 288 Also generate a left italic correction for each character
 289 equal to
 290 .I n
 291 thousandths of an em
 292 plus the amount by which the left edge of the character's bounding box
 293 is to the left of the character\[aq]s origin.
 294 .
 295 The left italic correction may be negative unless option
 296 .B \-m
 297 is given.
 298 .
 299 .IP
 300 This option is normally needed only with italic (or oblique) fonts.
 301 .
 302 The font files distributed with groff were created using an option of
 303 .B \-i50
 304 for italic fonts.
 305 .
 306 .TP
 307 .BI \-o out_file
 308 The output file is
 309 .I out_file
 310 instead of
 311 .IR font .
 312 .
 313 .TP
 314 .B \-k
 315 Omit any kerning data from the groff font.
 316 .
 317 This should be used only for mono-spaced fonts.
 318 .
 319 .TP
 320 .B \-m
 321 Prevent negative left italic correction values.
 322 .
 323 Roman font files distributed with groff were created with
 324 .B \-i0\ \-m
 325 to improve spacing with
 326 .BR @g@eqn (@MAN1EXT@).
 327 .
 328 .TP
 329 .B \-n
 330 Don't output a
 331 .B ligatures
 332 command for this font.
 333 .
 334 Use this with constant-width fonts.
 335 .
 336 .TP
 337 .B \-s
 338 The font is special.
 339 .
 340 The effect of this option is to add the
 341 .B special
 342 command to the font file.
 343 .
 344 .TP
 345 .B \-v
 346 Print version.
 347 .
 348 .TP
 349 .B \-x
 350 Don't use the built-in Adobe Glyph List.
 351 .
 352 .
 353 .\" --------------------------------------------------------------------
 354 .SH FILES
 355 .\" --------------------------------------------------------------------
 356 .
 357 .Tp \w'\fB@FONTDIR@/devps/download'u+2n
 358 .B @FONTDIR@/devps/DESC
 359 Device description file.
 360 .
 361 .TP
 362 .BI @FONTDIR@/devps/ F
 363 Font description file for font
 364 .IR F .
 365 .
 366 .TP
 367 .B @FONTDIR@/devps/download
 368 List of downloadable fonts.
 369 .
 370 .TP
 371 .B @FONTDIR@/devps/text.enc
 372 Encoding used for text fonts.
 373 .
 374 .TP
 375 .B @FONTDIR@/devps/generate/textmap
 376 Standard mapping.
 377 .
 378 .
 379 .\" --------------------------------------------------------------------
 380 .SH "SEE ALSO"
 381 .\" --------------------------------------------------------------------
 382 .
 383 .BR groff (@MAN1EXT@),
 384 .BR grops (@MAN1EXT@),
 385 .BR groff_font (@MAN5EXT@),
 386 .BR perl (1)
 387 .
 388 .
 389 .LP
 390 The groff info file, section \[oq]Using Symbols\[cq].
 391 .
 392 .
 393 .\" --------------------------------------------------------------------
 394 .SH COPYING
 395 .\" --------------------------------------------------------------------
 396 .co
 397 .
 398 .
 399 .\" Local Variables:
 400 .\" mode: nroff
 401 .\" End: