freetype1/contrib/ttf2pk/ttf2pk.doc

   1
   2 ttf2tfm -- TrueType to TFM converter
   3 ttf2pk  -- TrueType to PK converter
   4 ====================================
   5
   6 These  two auxiliary  programs make  TrueType fonts  usable  with TeX.
   7 ttf2tfm extracts the metric and kerning information of a TrueType font
   8 and  converts it into  metric files  usable by  TeX (quite  similar to
   9 afm2tfm which  is part of  the dvips package).  ttf2pk  rasterizes the
  10 glyph outlines of a TrueType font into a bitmap font in PK format.
  11
  12 Since a TrueType font often  contains more than 256 glyphs, some means
  13 are necessary to map a subset  of the TrueType glyphs into a TeX font.
  14 To do  this, two mapping  tables are needed:  the first maps  from the
  15 TrueType font  to a raw TeX font  (this mapping table is  used both by
  16 ttf2tfm and  ttf2pk), and  the second  maps from the  raw TeX  font to
  17 another  (virtual)  TeX  font   providing  all  kerning  and  ligature
  18 information needed by TeX.
  19
  20 We sometimes refer to this first  map as the `input' or `raw' map, and
  21 to the second as the `output' or `virtual' map.
  22
  23 This two  stage mapping  has the  advantage that one  raw font  can be
  24 accessed with various TeX encodings  (e.g. T1 and OT1) via the virtual
  25 font mechanism, and just one PK file is necessary.
  26
  27 For CJK fonts, a different mechanism is provided (see section `Subfont
  28 definition   files'   below).    Additionally,  rotated   glyphs   for
  29 pseudo-vertical writing  are supported -- if  possible, vertical glyph
  30 presentation forms are used from the font's GSUB table.
  31
  32
  33
  34 ttf2tfm
  35 =======
  36
  37 Usage:
  38
  39   ttf2tfm FILE[.ttf|.ttc] [OPTION]... [FILE[.tfm]]
  40
  41 Options (default values are given in brackets):
  42
  43 -c REAL             use REAL for height of small caps made with -V [0.8]
  44 -e REAL             widen (extend) characters by a factor of REAL [1.0]
  45 -E INT              select INT as the TTF encoding ID [1]
  46 -f INT              select INT as the font index in a TTC [0]
  47 -l                  create 1st/2nd byte ligatures in subfonts
  48 -n                  use PS names of TrueType font
  49 -N                  use only PS names and no cmap
  50 -O                  use octal for all character codes in the vpl file
  51 -p ENCFILE[.enc]    read ENCFILE for the TTF->raw TeX mapping
  52 -P INT              select INT as the TTF platform ID [3]
  53 -q                  suppress informational output
  54 -r OLDNAME NEWNAME  replace glyph name OLDNAME with NEWNAME
  55 -R RPLFILE[.rpl]    read RPLFILE containing glyph replacement names
  56 -s REAL             oblique (slant) characters by REAL, usually <<1 [0.0]
  57 -t ENCFILE[.enc]    read ENCFILE for the encoding of the vpl file
  58 -T ENCFILE[.enc]    equivalent to -p ENCFILE -t ENCFILE
  59 -u                  output only characters from encodings, nothing extra
  60 -v FILE[.vpl]       make a VPL file for conversion to VF
  61 -V SCFILE[.vpl]     like -v, but synthesize smallcaps as lowercase
  62 -x                  rotate subfont glyphs by 90 degrees
  63 -y REAL             move rotated glyphs down by a factor of REAL [0.25]
  64 --help              print this message and exit
  65 --version           print version number and exit
  66
  67
  68 The usage is  very similar to afm2tfm.  Please  consult the dvips info
  69 file  for  more details  on  the  various  parameters.  Here  we  will
  70 concentrate on the differences between afm2tfm and ttf2tfm.
  71
  72
  73 cmaps
  74 -----
  75
  76 Contrary to Type 1 PostScript  fonts (but similar to the new CID-keyed
  77 PostScript  fonts), most  TrueType  fonts have  more  than one  native
  78 mapping table, also called `cmap', which maps the (internal) TTF glyph
  79 indices to the (external) TTF  character codes.  Common examples are a
  80 mapping table to Unicode  encoded character positions and the standard
  81 Macintosh mapping.   To specify this  TrueType mapping table,  use the
  82 options `-P' and `-E'.  With `-P' you specify the platform ID; defined
  83 values are:
  84
  85            platform        platform ID (pid)
  86           ----------------------------------
  87            Apple Unicode        0
  88            Macintosh            1
  89            ISO                  2
  90            Microsoft            3
  91
  92 The encoding  ID depends  on the platform.   For pid=0, we  ignore the
  93 `-E' parameter (setting it to  zero) since the mapping table is always
  94 Unicode version 2.0.  For pid=1, the following table lists the defined
  95 values:
  96
  97        platform ID = 1
  98            script         encoding ID (eid)
  99           ---------------------------------
 100            Roman               0
 101            Japanese            1
 102            Chinese             2
 103            Korean              3
 104            Arabic              4
 105            Hebrew              5
 106            Greek               6
 107            Russian             7
 108            Roman Symbol        8
 109            Devanagari          9
 110            Gurmukhi           10
 111            Gujarati           11
 112            Oriya              12
 113            Bengali            13
 114            Tamil              14
 115            Telugu             15
 116            Kannada            16
 117            Malayalam          17
 118            Sinhalese          18
 119            Burmese            19
 120            Khmer              20
 121            Thai               21
 122            Laotian            22
 123            Georgian           23
 124            Armenian           24
 125            Maldivian          25
 126            Tibetan            26
 127            Mongolian          27
 128            Geez               28
 129            Slavic             29
 130            Vietnamese         30
 131            Sindhi             31
 132            Uninterpreted      32
 133
 134 Here are the ISO encoding IDs:
 135
 136        platform ID = 2
 137            encoding       encoding ID
 138           ----------------------------
 139            ASCII               0
 140            ISO 10646           1
 141            ISO 8859-1          2
 142
 143 And finally, the Microsoft encoding IDs:
 144
 145        platform ID = 3
 146            encoding       encoding ID
 147           ---------------------------
 148            Symbol              0
 149            Unicode 2.0         1
 150            Shift JIS           2
 151            GB 2312 (1980)      3
 152            Big 5               4
 153            KSC 5601 (Wansung)  5
 154            KSC 5601 (Johab)    6
 155
 156 The program will abort if  you specify an invalid platform/encoding ID
 157 pair.  Please  note that most fonts  have at most two  or three cmaps,
 158 usually corresponding to  the pid/eid pairs (1,0), (3,0),  or (3,1) in
 159 case of Latin based fonts.   Valid Microsoft fonts should have a (3,1)
 160 mapping table, but some fonts  exist (mostly Asian fonts) which have a
 161 (3,1)  cmap not  encoded  in  Unicode.  The  reason  for this  strange
 162 behavior is the  fact that some MS Windows  versions will reject fonts
 163 having a  non-Unicode cmap  (since all non-Unicode  Microsoft encoding
 164 IDs are for Asian specific MS Windows versions).
 165
 166 The `-P'  and `-E'  options to ttf2tfm  must be equally  specified for
 167 ttf2pk;  the corresponding  parameters  in ttfonts.map  are `Pid'  and
 168 `Eid', respectively.
 169
 170 The default pid/eid pair is (3,1).
 171
 172 If you  use the  `-N' switch,  all cmaps are  ignored, using  only the
 173 PostScript names  in the TrueType  font.  The corresponding  option in
 174 ttfonts.map is `PS=Only'.
 175
 176 If you use the `-n' switch, the default glyph names built into ttf2tfm
 177 are replaced with the PS glyph names found in the font.  In many cases
 178 this is  not what  you want because  the glyph  names in the  font are
 179 often  incorrect   or  non-standard.   The   corresponding  option  in
 180 ttfonts.map `PS=Yes'.
 181
 182
 183 input and output encodings
 184 --------------------------
 185
 186 You must  specify the encoding vectors  from the TrueType  font to the
 187 raw TeX font and from the raw TeX font to the virtual TeX font exactly
 188 as  with afm2tfm,  but  you  have more  possibilities  to address  the
 189 character  codes.  [With `encoding  vector' a  mapping table  with 256
 190 entries  in  form  of a  PostScript  vector  is  meant; see  the  file
 191 `T1-WGL4.enc' of this package for an example.]  With afm2tfm, you must
 192 access each glyph with its  Adobe glyph name, e.g.  `/quotedsingle' or
 193 `/Acircumflex'.  This has been extended with ttf2tfm; now you can (and
 194 sometimes must)  access the code  points and/or glyphs  directly using
 195 the following syntax for specifying the character position in decimal,
 196 octal,     or     hexadecimal     notation:     `/.c<decimal-number>',
 197 `/.c0<octal-number>',   or   `/.c0x<hexadecimal-number>'.    Examples:
 198 `/.c72', `/.c0646', `/.c0x48'.  To  access a glyph index directly, use
 199 the  character `g'  instead of  `c' in  the just  introduced notation.
 200 Example: `/.g0x32'.
 201
 202 [Note: The `.cXXX' notation makes no sense if `-N' is used.]
 203
 204 Another  possibility is  to use  the `-r  old-glyphname new-glyphname'
 205 switch to rename a glyph.  Example:
 206
 207   ttf2tfm ... -r .g0xc7 dotlessi -r hungarumlaut dblacute ...
 208
 209 Nevertheless, it  is not allowed to  use the `.gXXX'  or `.cXXX' glyph
 210 name construct for `new-glyphname'.
 211
 212 Alternatively, you can collect such  replacement pairs in a file which
 213 should have `.rpl' as extension, using the `-R' option.  The syntax is
 214 simple:  Each  line  contains  a  pair  `old-glyphname  new-glyphname'
 215 separated by  whitespace (without  the quotation marks).   The percent
 216 sign starts a  line comment; you can continue a  line with a backslash
 217 as the last character.  An example for a replacement file is `VPS.rpl'
 218 (to be  used in  conjunction with `ET5.enc'  for Vietnamese)  which is
 219 part of this package.
 220
 221 The `-r' and `-R' switches are  ignored for subfonts or if no encoding
 222 tables are specified.  For ttf2pk, the corresponding option to `-R' is
 223 `Replacement'.    Single   replacements    are   directly   given   as
 224 old_glyphname=newglyphname in ttfonts.map.
 225
 226 For pid/eid pairs  (1,0) and (3,1), both ttf2tfm  and ttf2pk recognize
 227 built-in default Adobe glyph names;  the former pair follows the names
 228 given  in Appendix E  of the  book `Inside  Macintosh', volume  6, the
 229 latter uses  the names  given in the  TrueType Specification  (WGL4, a
 230 Unicode subset).   Note that Adobe glyph  names are not  unique and do
 231 sometimes differ:  E.g., many  PS fonts have  the glyph  `mu', whereas
 232 this glyph is called `mu1' in the WGL4 character set to distinguish it
 233 from the real  Greek letter mu.  You can find  those mapping tables in
 234 the source code file `ttfenc.c'.
 235
 236 On the other hand, the switches `-n' and `-N' make ttf2tfm read in and
 237 use the  PostScript names in the  TrueType font itself  (stored in the
 238 font's `post' table) instead of the default Adobe glyph names.
 239
 240 If you  don't select an  input encoding, the  first 256 glyphs  of the
 241 TrueType font with  a valid entry in the selected  cmap will be mapped
 242 to  the TeX  raw font  (without the  `-q' option  ttf2tfm  prints this
 243 mapping  table to  standard output),  followed by  all glyphs  not yet
 244 addressed in  the selected  cmap.  However, some  code points  for the
 245 (1,0)  pid/eid pair  are omitted  since they  do not  represent glyphs
 246 useful  for  TeX:  0x00  (null), 0x08  (backspace),  0x09  (horizontal
 247 tabulation), 0x0d (carriage return),  and 0x1d (group separator).  The
 248 `invalid character' with glyph index 0 will be omitted too.
 249
 250 If you  select the `-N' switch,  the first 256 glyphs  of the TrueType
 251 font  with a  valid PostScript  name  will be  used in  case no  input
 252 encoding  is specified.   Again, some  glyphs are  omitted: `.notdef',
 253 `.null', and `nonmarkingreturn'.
 254
 255 If you don't select an  output encoding, ttf2tfm uses the same mapping
 256 table as  afm2tfm would use (you can  find it in the  source code file
 257 texenc.c); it  corresponds to  TeX typewriter text.   Unused positions
 258 (either caused  by empty code points  in the mapping  table or missing
 259 glyphs in the TrueType font)  will be filled (rather arbitrarily) with
 260 characters  present in  the input  encoding but  not specified  in the
 261 output  encoding (without  the `-q'  option ttf2tfm  prints  the final
 262 output encoding to standard output).   Use the `-u' option if you want
 263 only  glyphs in  the  virtual font  which  are defined  in the  output
 264 encoding file, and nothing more.
 265
 266 One feature missing  in afm2tfm has been added which  is needed by the
 267 LaTeX T1  encoding: ttf2tfm will construct the  glyph `Germandbls' (by
 268 simply concatenating to `S' glyphs) even for normal fonts if possible.
 269 It appears  in the glyph  list (written to  stdout) as the  last item,
 270 marked with  an asterisk.  Since  this isn't a  real glyph it  will be
 271 available only in the virtual font.
 272
 273 For  both  input  and  output  encoding, an  empty  code  position  is
 274 represented by the glyph name `.notdef'.
 275
 276 In encoding files, you can use `\' as the final character of a line to
 277 indicate that the input is  continued on the next line.  The backslash
 278 and the following newline character will be removed.
 279
 280 ttf2tfm  returns  0 on  success  and 1  on  error;  warning and  error
 281 messages are written to standard error.
 282
 283
 284 other options
 285 -------------
 286
 287 You can select  the font in a TrueType  font collection (which usually
 288 has  the  extension  `.ttc')  with  `-f';  the  default  value,  zero,
 289 specifies  the first  font.  For  fonts not  being a  collection, this
 290 parameter is ignored.
 291
 292 The  option `-l' makes  ttf2tfm create  ligatures in  subfonts between
 293 first and second bytes of  all the original character codes.  Example:
 294 Character code  0xABCD maps to  character position 123 in  subfont 45.
 295 Then a ligature in subfont  45 between position 0xAB and 0xCD pointing
 296 to character  123 will  be produced.  The  fonts of the  Korean HLaTeX
 297 package use this feature.
 298
 299 To produce  glyphs rotated by 90 degrees  counter-clockwise, use `-x'.
 300 If the  font contains  a GSUB table  (with feature `vert')  to specify
 301 vertical glyph  presentation forms, both  ttf2pk and ttf2tfm  will use
 302 it.  This  will work  only in subfont  mode.  The y-offset  of rotated
 303 glyphs can be specified with  the `-y' option; its parameter gives the
 304 fractional amount of shifting downwards  (the unit is one EM).  If not
 305 specified, a value of 0.25 (em) is used.
 306
 307
 308
 309 ttf2pk
 310 ======
 311
 312 Usage:
 313
 314   ttf2pk [-q] [-n] FONT DPI
 315   ttf2pk -t [-q] FONT
 316
 317 Options:
 318
 319 -q              suppresses informational output
 320 -n              only use `.pk' as extension
 321 -t              test for FONT (returns 0 on success)
 322 --help          print this message and exit
 323 --version       print version number and exit
 324
 325
 326 The FONT parameter must correspond to an entry in the file ttfonts.map
 327 (see below  for details), otherwise error  code 2 is  returned -- this
 328 can be  used for scripts like  mktexpk to test whether  the given font
 329 name is a (registered) TrueType font.
 330
 331 Another possibility  is to  use the `-t'  switch which will  print the
 332 line  of ttfonts.map  corresponding to  FONT and  return 0  on success
 333 (`-q' suppresses any output).
 334
 335 DPI specifies the intended resolution  (we always assume a design size
 336 of 10pt).
 337
 338
 339 ttfonts.map
 340 -----------
 341
 342 ttf2pk  uses,  similar  to   dvips,  a  font  definition  file  called
 343 ttfonts.map.  The  parameters specified to ttf2tfm  are here preserved
 344 -- ttf2tfm writes out  to standard output, as the  last line, a proper
 345 configuration entry for ttfonts.map.
 346
 347 As an example, a call to
 348
 349   ttf2tfm arial -s 0.25 -P 1 -E 0 -r .g0xc7 caron \
 350                 -p 8r.enc -t T1-WGL4.enc -v arialsx arials
 351
 352 will produce the following line:
 353
 354   arials   arial Slant=0.25 Encoding=8r.enc Pid=1 Eid=0 .g0xc7=caron
 355
 356 The output encoding given with  `-t' for the virtual font `arialsx' is
 357 immaterial to ttf2pk (nevertheless, input encoding files must have the
 358 same format as  with ttf2tfm, and all said  above about encoding files
 359 holds).
 360
 361 Here  a   table  listing  the  various  ttf2tfm   parameters  and  its
 362 corresponding ttfonts.map entries:
 363
 364         -s        Slant
 365         -e        Extend
 366         -p        Encoding
 367         -f        Fontindex
 368         -P        Pid
 369         -E        Eid
 370         -n        PS=Yes
 371         -N        PS=Only
 372         -R        Replacement
 373         -x        Rotate=Yes
 374         -y        Y-Offset
 375
 376 Single replacement glyph  names given to ttf2tfm with  the `-r' switch
 377 are directly specified with old-glyphname=new-glyphname.  For subfonts
 378 or if no encoding file is given, replacement glyphs are ignored.
 379
 380 One  additional   parameter  in  ttfonts.map  is   unique  to  ttf2pk:
 381 `Hinting', which can take the  values `On' or `Off'.  Some fonts (e.g.
 382 the CJK part  of cyberbit.ttf) are rendered incorrectly  if hinting is
 383 activated.  Default  is `On' (you can  also use `Yes',  `No', `1', and
 384 `0').
 385
 386 The format of ttfonts.map is  simple.  Each line defines a font; first
 387 comes the TeX font name, then its TrueType font file name, followed by
 388 the parameters in any order.   Case is significant (even for parameter
 389 names); the parameters are separated from its values by an equal sign,
 390 with possible whitespace surrounding  it.  ttf2pk reads in ttfonts.map
 391 line by line,  continuing until the TeX font  specified on the command
 392 line is found,  otherwise the programs exits with  error code 2.  Thus
 393 you  can use  any character  invalid in  a TeX  font name  to  start a
 394 comment line.
 395
 396 In both ttfonts.map and encoding files, use `\' as the final character
 397 of a  line to indicate that the  input is continued on  the next line.
 398 The backslash and the following newline character will be removed.
 399
 400 ttf2pk will abort if it can't  find and read the TeX font metrics file
 401 of the given TeX font name.
 402
 403
 404 Subfont definition files
 405 ========================
 406
 407 CJK (Chinese/Japanese/Korean)  fonts usually contain  several thousand
 408 glyphs; to use them with TeX it is necessary to split such large fonts
 409 into subfonts.  Subfont definition files (usually having the extension
 410 `.sfd') are a  simple means to do this smoothly.   A subfont file name
 411 usually consists of a prefix, a subfont infix, and a postfix (which is
 412 empty in most cases), e.g.
 413
 414     ntukai23 -> prefix: ntukai, infix: 23, postfix: (empty)
 415
 416 Here the syntax of a line in an SFD file, describing one subfont:
 417
 418   <whitespace> <infix> <whitespace> <ranges> <whitespace> `\n'
 419
 420   <infix> := anything except whitespace. It's best to use only
 421              alphanumerical characters.
 422   <whitespace> := space, formfeed, carriage return, horizontal and
 423                   vertical tabs -- no newline characters.
 424   <ranges> := <ranges> <whitespace> <codepoint> |
 425               <ranges> <whitespace> <range> |
 426               <ranges> <whitespace> <offset> <whitespace> <range>
 427
 428   <codepoint> := <number>
 429   <range> := <number> `_' <number>
 430   <offset> := <number> `:'
 431
 432   <number> := hexadecimal (prefix `0x'), decimal, or octal
 433               (prefix `0')
 434
 435 A line can  be continued on the next line with  a backslash ending the
 436 line.  The  ranges must not overlap;  offsets have to be  in the range
 437 0-255.
 438
 439 Example:
 440
 441   The line
 442
 443     03   10: 0x2349 0x2345_0x2347
 444
 445   assigns to  the code  positions 10,  11, 12, and  13 of  the subfont
 446   having the  infix `03' the  character codes 0x2349,  0x2345, 0x2346,
 447   and 0x2347, respectively.
 448
 449 The SFD files  in the distribution are customized  for the CJK package
 450 for LaTeX.
 451
 452 You have to  embed the SFD file  into the TFM font name  (at the place
 453 where  the infix  will appear)  surrounded by  two `@'  signs,  on the
 454 command  line resp.  the  ttfonts.map file;  both  ttf2tfm and  ttf2pk
 455 switch then to subfont mode.
 456
 457 Subfont mode disables the options  `-n', `-N', `-p', `-r', `-R', `-t',
 458 `-T', `-u', `-v',  and `-V' for ttf2tfm; similarly,  no `Encoding' and
 459 `Replacement'  parameter  resp.  single  replacement glyph  names  are
 460 allowed in ttfonts.map.
 461
 462 ttf2tfm will create  ALL subfont TFM files specified  in the SFD files
 463 (provided the subfont contains glyphs) in one run.
 464
 465 Example:
 466
 467   The call
 468
 469     ttf2tfm ntukai.ttf ntukai@/usr/local/lib/ttf2tfm/Big5@
 470
 471   will  use `/usr/local/lib/ttf2tfm/Big5.sfd',  producing  the subfont
 472   files ntukai01.tfm, ntukai02.tfm etc.
 473
 474   ttf2pk should be then called on the subfonts directly:
 475
 476     ttf2pk ntukai01 600
 477     ttf2pk ntukai02 600
 478     ...
 479
 480
 481 Some notes on file searching
 482 ============================
 483
 484 Both ttf2pk and  ttf2tfm use either the kpathsea,  emtexdir, or MiKTeX
 485 library  for searching  files (emtexdir  will work  only  on operating
 486 systems  which  have  an  MS-DOSish background,  i.e.   MS-DOS,  OS/2,
 487 Windows; MiKTeX is specific to MS Windows).
 488
 489 During compilation, you have to define HAVE_KPATHSEA, HAVE_EMTEXDIR,
 490 or MIKTEX to activate the specific file search code.
 491
 492 As  a last  resort, both  programs can  be compiled  without  a search
 493 library; the searched  files must be then in  the current directory or
 494 specified with a path.  Default extensions will be appended also (with
 495 the exception that only `.ttf' is appended and not `.ttc').
 496
 497
 498 kpathsea
 499 --------
 500
 501 Please note  that older  versions of kpathsea  (<3.2) have  no special
 502 means to search for TrueType fonts  and related files, thus we use the
 503 paths for PostScript related stuff.  The actual version of kpathsea is
 504 displayed  on screen if  you call  either ttf2pk  or ttf2tfm  with the
 505 `--version' command line switch.
 506
 507 Here  is a  table  of the  file  type and  the corresponding  kpathsea
 508 variables.   TTF2PKINPUTS  and   TTF2TFMINPUTS  are  program  specific
 509 environment variables introduced in kpathsea version 3.2:
 510
 511     .ttf and .ttc        TTFONTS
 512     ttfonts.map          TTF2PKINPUTS
 513     .enc                 TTF2PKINPUTS, TTF2TFMINPUTS
 514     .rpl                 TTF2PKINPUTS, TTF2TFMINPUTS
 515     .tfm                 TFMFONTS
 516     .sfd                 TTF2PKINPUTS, TTF2TFMINPUTS
 517
 518 And here the same for pre-3.2-versions of kpathsea:
 519
 520     .ttf and .ttc        T1FONTS
 521     ttfonts.map          TEXCONFIG
 522     .enc                 TEXPSHEADERS
 523     .rpl                 TEXPSHEADERS
 524     .tfm                 TFMFONTS
 525     .sfd                 TEXPSHEADERS
 526
 527 Finally, the same for pre-3.0-versions:
 528
 529     .ttf and .ttc        DVIPSHEADERS
 530     ttfonts.map          TEXCONFIG
 531     .enc                 DVIPSHEADERS
 532     .rpl                 DVIPSHEADERS
 533     .tfm                 TFMFONTS
 534     .sfd                 DVIPSHEADERS
 535
 536 Please  consult the  info  files  for kpathsea  for  details on  these
 537 variables.  The decision whether to use the old or the new scheme will
 538 be done during compilation.
 539
 540 You  should set  the TEXMFCNF  variable  to the  directory where  your
 541 texmf.cnf configuration file resides.
 542
 543 The default TDS location for the files in the data subdirectory is
 544
 545   $TEXMF/ttf2tfm
 546
 547 (or $TEXMF/ttf2pk; you should either make a symbolic link
 548
 549   % ln -s $TEXMF/ttf2tfm $TEXMF/ttf2pk
 550
 551 or set the variable TTF2PKINPUTS to $TEXMF/ttf2tfm  for newer kpathsea
 552 versions)
 553
 554 Here  is the  proper command  to find  out to  which value  a kpathsea
 555 variable is set (we use  `TTFONTS' as an example).  This is especially
 556 useful if  a variable  isn't set in  texmf.cnf or in  the environment,
 557 thus  pointing to  the  default  value which  is  hard-coded into  the
 558 kpathsea library.
 559
 560   % kpsewhich --progname=ttf2tfm --expand-var='$TTFONTS'
 561
 562 We  select the  program  name also  since  it is  possible to  specify
 563 variables  which are searched  only for  a certain  program --  in our
 564 example it would be `TTFONTS.ttf2tfm'.
 565
 566 A similar but not identical method is to say
 567
 568   % kpsewhich --progname=ttf2tfm --show-path='truetype fonts'
 569
 570 [A  full list of  format types  can be  obtained by  saying `kpsewhich
 571 --help' on the command line  prompt.]  This is exactly the how ttf2tfm
 572 (and ttf2pk) search for files;  the disadvantage is that all variables
 573 are expanded which can cause very long string.
 574
 575
 576 emtexdir
 577 --------
 578
 579 Here the list of suffixes  and its related environment variables to be
 580 set in autoexec.bat (resp. in config.sys for OS/2):
 581
 582     .ttf and .ttc        TTFONTS
 583     ttfonts.map          TTFCFG
 584     .enc                 TTFCFG
 585     .rpl                 TTFCFG
 586     .tfm                 TEXTFM
 587     .sfd                 TTFCFG
 588
 589 With other words,  all files in the data subdirectory  should be moved
 590 to a place in your emtex tree with TTFCFG pointing to this directory.
 591
 592 If one of the variables isn't  set, a warning message is emitted.  The
 593 current directory will always  be searched.  As usual, one exclamation
 594 mark appended to a directory path causes subdirectories one level deep
 595 to be searched, two exclamation  marks causes all subdirectories to be
 596 searched.  Example:
 597
 598   TTFONTS=c:\fonts\truetype!!;d:\myfonts\truetype!
 599
 600 Constructions like `c:\fonts!!\truetype' aren't possible.
 601
 602
 603 MiKTeX
 604 ------
 605
 606 Both  ttf2tfm  and ttf2pk  have  been  fully  integrated into  MiKTeX.
 607 Please refer to  the documentation of MiKTeX for  more details on file
 608 searching.
 609
 610
 611
 612 A full example
 613 ==============
 614
 615 Here an example how to handle the font `verdana.ttf' and its variants.
 616
 617
 618 1. Construct the font name
 619 --------------------------
 620
 621   [This is  the most complicated part --  in case you are  too lazy to
 622   construct font names compliant  to TeX's `fontname' scheme, just use
 623   your own names.]
 624
 625   Using the `ftdump' utility (which  is part of FreeType) you can find
 626   out the  PostScript name of the  specific TTF which  is probably the
 627   best  choice  to adapt  TrueType  fonts  to the  PostScript-oriented
 628   `fontname' scheme.
 629
 630   In our example, the PostScript name is `Verdana'.
 631
 632   `fontname' uses the scheme
 633
 634     S TT W [V...] [N] [E] [DD]
 635
 636   as documented in `fontname.texi' resp. `fontname.dvi'.  Now you have
 637   to check the various mapping files:
 638
 639      S: supplier.map: `j'  for `Microsoft'
 640     TT: typeface.map: `vn' for `Verdana'
 641      W: weight.map:   `r'  for `Regular Roman',
 642                       `b'  for `bold'
 643      V,
 644      N: variant.map:  `8r' for the raw base font
 645                       `8t' for the virtual font
 646                            (i.e., LaTeX's T1 encoding)
 647                       [additionally an inserted `c' for small caps,
 648                        `o' for slanted (`oblique'), or `i' for italic
 649                        fonts]
 650
 651   Here the standard combinations:
 652
 653     `jvnr8r' for the default base font.
 654       `jvnr8t'  for the virtual default font.
 655       `jvnrc8t' for the virtual font with small caps. [As you can see,
 656                 no additional raw font is needed.]
 657     `jvnro8r' for the slanted base font.
 658       `jvnro8t' for the virtual slanted font.
 659
 660   The corresponding variants are:
 661
 662     bold:            verdanab.ttf -> jvnb{8r,8t}
 663       small caps:                    jvnbc8t
 664       slanted:                       jvnbo{8r,8t}
 665     italic:          verdanai.ttf -> jvni{8r,8t}
 666     bold and italic: verdanaz.ttf -> jvnbi{8r,8t}
 667
 668
 669 2. Font definition files
 670 ------------------------
 671
 672   The FD file should be called  `t1jvn.fd' (as you can see, this is T1
 673   encoding).  It  is very  similar to `t1ptm.fd',  part of  the PSNFSS
 674   package (which  can be  found in almost  all TeX  distributions).  A
 675   `verdana.sty' file can also be modeled after `times.sty'.
 676
 677
 678 3. Calling ttf2tfm
 679 ------------------
 680
 681   To make the  example simpler, we use `T1-WGL4.enc'  for both the raw
 682   and  the  virtual encoding.   This  should  be  sufficient for  most
 683   TrueType  fonts mapped to  T1 encoding.   Other packages  may define
 684   other encodings  (e.g. the `t2' package available  from CTAN defines
 685   mapping files for Cyrillic encodings) -- it may also be necessary to
 686   use the `-n' or `-N' switch together with replacement glyph names to
 687   access all glyph names in the TrueType font.
 688
 689   To create `jvnr8r' and `jvnr8t', just call
 690
 691     ttf2tfm verdana -T T1-WGL4 -v jvnr8t jvnr8r
 692     vptovf jvnr8t
 693
 694   For `jvnrc8t', do
 695
 696     ttf2tfm verdana -T T1-WGL4 -V jvnrc8t jvnr8r
 697     vptovf jvnrc8t
 698
 699   Note  that almost  always some  warnings will  appear  about missing
 700   glyphs.
 701
 702   The last line  written to stdout by ttf2tfm is  a suitable entry for
 703   ttfonts.map --  since ttf2pk doesn't care about  virtual fonts, both
 704   calls below produce the same.
 705
 706   Now  just  repeat this  procedure.   For  slanted  fonts you  should
 707   additionally use the switch `-s 0.176' (of course you can change the
 708   slanting amount to make it fit your needs).
 709
 710
 711
 712 Problems
 713 ========
 714
 715 Most vptovf  implementations allow only  100 bytes for the  TFM header
 716 (the limit is  1024 in the TFM file itself): 8  bytes for checksum and
 717 design size, 40 bytes for the  family name, 20 bytes for the encoding,
 718 and 4  bytes for  a face byte.   There remain  only 28 bytes  for some
 719 additional information which is  used by ttf2tfm for an identification
 720 string (which  is essentially  a copy of  the command line),  and this
 721 limit is always exceeded.
 722
 723 The optimal solution is to increase the value of `max_header_bytes' in
 724 the file vptovf.w  (and probably pltotf.w) to, say,  400 and recompile
 725 vptovf  (and  pltotf).  Otherwise  you'll  get  some (harmless)  error
 726 messages like
 727
 728   This HEADER index is too big for my present table size
 729
 730 which can be safely ignored.
 731
 732
 733 --- end of ttf2pk.doc ---