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