doc/ttfautohint-1.pandoc

   1 % The ttfautohint library
   2 % Werner Lemberg
   3 % April 2012
   4
   5
   6
   7 Introduction
   8 ============
   9
  10 **ttfautohint** is a library which takes a TrueType font as the input,
  11 removes its bytecode instructions (if any), and returns a new font where all
  12 glyphs are bytecode hinted using the information given by FreeType's
  13 autohinting module.  The idea is to provide the excellent quality of the
  14 autohinter on platforms which don't use FreeType.
  15
  16 The library has a single API function, `TTF_autohint`, which is described
  17 [below](#TTF_autohint).
  18
  19 Bundled with the library there are two front-end programs, `ttfautohint` and
  20 `ttfautohintGUI`, being a command line and GUI application, respectively.
  21
  22
  23
  24 Background
  25 ==========
  26
  27 [Scholarly paper](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf)
  28
  29
  30 Feature Analysis
  31 ----------------
  32
  33 TODO
  34
  35
  36 Blue Zones
  37 ----------
  38
  39 TODO
  40
  41
  42 Hint Sets
  43 ---------
  44
  45 A *hint set* is the *optimal* configuration for a given PPEM (pixel per EM)
  46 value.  However, it can also hint larger and smaller values.
  47
  48 Internally, ttfautohint creates hint sets for every PPEM value in the range
  49 given by the `--hinting-range-min` and `--hinting-range-max` options (this
  50 is a per-glyph operation).  If it differs to the current one, a new set is
  51 emitted.  For some glyphs it is possible that one set covers, say, the range
  52 8px-1000px, while other glyphs need 10 or more such sets.
  53
  54 Consider, for example, this glyph:
  55
  56      __    __    __
  57     |  |  |  |  |  |
  58     |  |  |  |  |  |
  59     |  |  |  |__|  |         -> y2
  60     |  |__|        |         -> y1
  61     |              |
  62     |______________|
  63
  64
  65 For small PPEM values, the horizontal segments with vertical coordinates y1
  66 and y2 get unified, being positioned on one horizontal line.  Starting with
  67 a certain (larger) PPEM value, this no longer happens, and ttfautohint
  68 creates a new hint set to accomodate this situation.
  69
  70 Obviously, the more hint sets get emitted, the larger the bytecode
  71 ttfautohint adds to the output font.
  72
  73
  74 The '.ttfautohint' glyph
  75 ------------------------
  76
  77 TODO
  78
  79
  80 Scripts
  81 -------
  82
  83 ttfautohint checks which autohinting module should be used to hint a
  84 specific glyph.  To do so, it checks a glyph's Unicode character code
  85 whether it belongs to a given script.  Currently, only FreeType's 'latin'
  86 autohinting module is implemented, but more are expected to come.  Here is
  87 the hardcoded list of character ranges which are hinted by this 'latin'
  88 module.  As you can see, this also covers some non-latin scripts (in the
  89 Unicode sense) which have similar typographical properties.
  90
  91     Character range    Description
  92   -------------------  -------------
  93   0x0020 - 0x007F      Basic Latin (no control chars)
  94   0x00A0 - 0x00FF      Latin-1 Supplement (no control chars)
  95   0x0100 - 0x017F      Latin Extended-A
  96   0x0180 - 0x024F      Latin Extended-B
  97   0x0250 - 0x02AF      IPA Extensions
  98   0x02B0 - 0x02FF      Spacing Modifier Letters
  99   0x0300 - 0x036F      Combining Diacritical Marks
 100   0x0370 - 0x03FF      Greek and Coptic
 101   0x0400 - 0x04FF      Cyrillic
 102   0x0500 - 0x052F      Cyrillic Supplement
 103   0x1D00 - 0x1D7F      Phonetic Extensions
 104   0x1D80 - 0x1DBF      Phonetic Extensions Supplement
 105   0x1DC0 - 0x1DFF      Combining Diacritical Marks Supplement
 106   0x1E00 - 0x1EFF      Latin Extended Additional
 107   0x1F00 - 0x1FFF      Greek Extended
 108   0x2000 - 0x206F      General Punctuation
 109   0x2070 - 0x209F      Superscripts and Subscripts
 110   0x20A0 - 0x20CF      Currency Symbols
 111   0x2150 - 0x218F      Number Forms
 112   0x2460 - 0x24FF      Enclosed Alphanumerics
 113   0x2C60 - 0x2C7F      Latin Extended-C
 114   0x2DE0 - 0x2DFF      Cyrillic Extended-A
 115   0xA640 - 0xA69F      Cyrillic Extended-B
 116   0xA720 - 0xA7FF      Latin Extended-D
 117   0xFB00 - 0xFB06      Alphab. Present. Forms (Latin Ligs)
 118   0x1D400 - 0x1D7FF    Mathematical Alphanumeric Symbols
 119
 120 If a glyph's character code is not covered by a script range, it is not
 121 hinted (or rather, it gets hinted by the 'dummy' autohinting module which
 122 essentially does nothing).  This can be changed by specifying a *fallback
 123 script* with option `--latin-fallback`.
 124
 125
 126
 127 `ttfautohint` and `ttfautohintGUI`
 128 ==================================
 129
 130 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
 131 looks quite similar; the used toolkit is [Qt], which in turn uses the
 132 platform's native widgets.
 133
 134 ![`ttfautohintGUI` on GNU/Linux running KDE](ttfautohintGUI.png)
 135
 136 Both the GUI and console version share the same features, to be discussed in
 137 the next subsection.
 138
 139
 140 Options
 141 -------
 142
 143 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
 144 the same command line options as `ttfautohint`, setting default values for
 145 the GUI.
 146
 147 Long options can be given with one or two dashes, and with and without equal
 148 sign between option and argument.  This means that the following forms are
 149 acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and `--foo`\ *bar*.
 150
 151 ### Hint Set Ranges
 152
 153 `--hinting-range-min=`*n*, `-l`\ *n*
 154 :   The minimum PPEM value (in pixels) at which hint sets are created.  The
 155     default value for *n* is\ 8.
 156 `--hinting-range-max=`*n*, `-r`\ *n*
 157 :   The maximum PPEM value (in pixels) at which hint sets are created.  The
 158     default value for *n* is 1000.
 159
 160 ### Hinting Limit
 161
 162 `--hinting-limit=`*n*, `-G`\ *n*
 163 :   The *hinting limit* is the PPEM value (in pixels) where hinting gets
 164     switched off completely (using the `INSTCTRL` bytecode instruction); it
 165     has zero impact on the file size.  The default value for *n* is 1000.
 166
 167     Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
 168     uses the hinting configuration for 'hinting-range-max'.
 169
 170     To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
 171     Hinting Limit' box in the GUI).  Since this will cause internal math
 172     overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
 173     is strongly recommended to not use this except for testing purposes.
 174
 175 ### Fallback Script
 176
 177 `--latin-fallback`, `-f`
 178 :   Set fallback script to 'latin', this is, use the 'latin' autohinting
 179     module instead of 'none' for all glyphs which can't be assigned to a
 180     script.  See [above](#scripts) for more details.
 181
 182 ### Pre-hinting
 183
 184 `--pre-hinting`, `-p`
 185 :   *Pre-hinting* means that a font's original bytecode is applied to all
 186     glyphs before it is replaced with bytecode created by ttfautohint.
 187     This makes only sense if your font already has some hints in it which
 188     modify the shape even at EM size (normally 2048px); for example, some
 189     CJK fonts need this because the bytecode is used to scale and shift
 190     subglyphs.  For most fonts, however, this is not the case.
 191
 192 ### ttfautohint Info
 193
 194 `--no-info`, `-i`
 195 :   Don't add ttfautohint version and command line information to the
 196     version string or strings (with name ID\ 5) in the font's 'name' table.
 197     In the GUI it is handled the opposite: If you check the 'Add ttfautohint
 198     info' box, information is added to the 'name' table.
 199
 200 ### Symbol Fonts
 201
 202 `--symbol`, `-s`
 203 :   Use default values for standard stem width and height instead of
 204     deriving them from latin character 'o'.  Use this option (usually in
 205     combination with option `--latin-fallback`) to hint symbol fonts, for
 206     example, which lack character 'o', at the expense of possibly poor
 207     hinting results at small sizes.
 208
 209 ### Font License Restrictions
 210
 211 `--ignore-permissions`, `-i`
 212 :   By default, fonts which have bit\ 1 set in the 'fsType' field of the
 213     'OS/2' table are rejected.  If you have a permission of the font's legal
 214     owner to modify the font, specify this command line option.
 215
 216     If this option is not set, `ttfautohintGUI` shows a dialogue to handle
 217     such fonts if necessary.
 218
 219 ### Miscellaneous
 220
 221 `--help`, `-h`
 222 :   On the console, print a brief documentation on standard output and exit.
 223     This doesn't work with `ttfautohintGUI` on MS Windows.
 224
 225 `--version`, `-v`
 226 :   On the console, print version information on standard output and exit.
 227     This doesn't work with `ttfautohintGUI` on MS Windows.
 228
 229
 230
 231 Samples
 232 =======
 233
 234
 235 Roboto
 236 ------
 237
 238 TODO
 239
 240
 241 Ubuntu
 242 ------
 243
 244 TODO
 245
 246
 247 [Qt]: http://qt-project.org