Lots of minor changes

Author: mdboom

docstrings/glyph.py

@@ -91,8 +91,7 @@
 
 Computing the control box is very fast, while getting the bounding box
 can take much more time as it needs to walk over all segments and arcs
-in the outline. To get the latter, you can use the ‘ftbbox’ component
-which is dedicated to this single task (TODO).
+in the outline.
 
 Parameters
 ----------

docstrings/outline.py

@@ -117,13 +117,18 @@
     be called.
 
 shift : int, optional
-    The shift that is applied to coordinates before they are sent to
+    The number of bits to shift coordinates before they are sent to
     the emitter.
 
 delta : int, optional
     The delta that is applied to coordinates before they are sent to
     the emitter, but after the shift.
 
+    The transformation applied by shift and delta is::
+
+        x' = (x << shift) - delta
+        y' = (y << shift) - delta
+
 Examples
 --------
 

docstrings/tt_header.py

@@ -157,11 +157,3 @@
 
 - -2: Like -1, but also contains neutrals
 """
-
-TT_Header_index_to_loc_format = """
-TODO
-"""
-
-TT_Header_glyph_data_format = """
-TODO
-"""

docstrings/tt_os2.py

@@ -347,41 +347,172 @@ class (either by a font designer or by some automated means) the
 """
 
 TT_OS2_typo_ascender = """
-TODO
+The typographic ascender for this font. Remember that this is not the
+same as `TT_HoriHeader.ascender`, which Apple defines in a far
+different manner.
+
+The suggested usage for `typo_ascender` is that it be used in
+conjunction with `TT_Header.units_per_em` to compute a typographically
+correct default line spacing. The goal is to free applications from
+Macintosh or Windows-specific metrics which are constrained by
+backward compatibility requirements. These new metrics, when combined
+with the character design widths, will allow applications to lay out
+documents in a typographically correct and portable fashion.
+
+For CJK (Chinese, Japanese, and Korean) fonts that are intended to be
+used for vertical writing (in addition to horizontal writing), the
+required value for `typo_ascender` is that which describes the top of
+the of the ideographic em-box. For example, if the ideographic em-box
+of the font extends from coordinates 0,-120 to 1000,880 (that is, a
+1000x1000 box set 120 design units below the Latin baseline), then the
+value of `typo_ascender` must be set to 880. Failing to adhere to these
+requirements will result in incorrect vertical layout.
 """
 
 TT_OS2_typo_descender = """
-TODO
+The typographic descender for this font. Remember that this is not the
+same as the `TT_HoriHeader.descender`, which Apple defines in a far
+different manner.
+
+The suggested usage for `typo_descender` is that it be used in
+conjunction with `TT_Header.units_per_em` to compute a typographically
+correct default line spacing. The goal is to free applications from
+Macintosh or Windows-specific metrics which are constrained by
+backward compatability requirements. These new metrics, when combined
+with the character design widths, will allow applications to lay out
+documents in a typographically correct and portable fashion.
+
+For CJK (Chinese, Japanese, and Korean) fonts that are intended to be
+used for vertical writing (in addition to horizontal writing), the
+required value for `typo_descender` is that which describes the bottom
+of the of the ideographic em-box. For example, if the ideographic
+em-box of the font extends from coordinates 0,-120 to 1000,880 (that
+is, a 1000x1000 box set 120 design units below the Latin baseline),
+then the value of `typo_descender` must be set to -120. Failing to
+adhere to these requirements will result in incorrect vertical layout.
 """
 
 TT_OS2_typo_line_gap = """
-TODO
-"""
+The typographic line gap for this font. Remember that this is not the
+same as `TT_HoriHeader.line_gap`, which Apple defines in a far
+different manner.
+
+The suggested usage for `typo_line_gap` is that it be used in
+conjunction with `TTHeader.units_per_em` to compute a typographically
+correct default line spacing. Typical values average 7-10% of units
+per em. The goal is to free applications from Macintosh or
+Windows-specific metrics which are constrained by backward
+compatability requirements. These new metrics, when combined with the
+character design widths, will allow applications to lay out documents
+in a typographically correct and portable fashion.  """
 
 TT_OS2_win_ascent = """
-TODO
+The ascender metric for Windows. This, too, is distinct from Apple's
+`TT_HoriHeader.ascender` value and from the `typo_ascender`
+values. `win_ascent` is computed as the ``y_max`` for all characters
+in the Windows ANSI character set. `win_ascent` is used to compute the
+Windows font height and default line spacing. For platform 3 encoding
+0 fonts, it is the same as `TT_Header.y_max`. Windows will clip the
+bitmap of any portion of a glyph that appears above this value. Some
+applications use this value to determine default line spacing. This is
+strongly discouraged. The typographic ascender, descender and line gap
+fields in conjunction with `TT_Header.units_per_em` should be used for
+this purpose. Developers should set this field keeping the above
+factors in mind.
+
+If any clipping is unacceptable, then the value should be set to
+`TT_Header.y_max`.
+
+However, if a developer desires to provide appropriate default line
+spacing using this field, for those applications that continue to use
+this field for doing so (against OpenType recommendations), then the
+value should be set appropriately. In such a case, it may result in
+some glyph bitmaps being clipped.
 """
 
 TT_OS2_win_descent = """
-TODO
+The descender metric for Windows. This, too, is distinct from Apple's
+`TT_HoriHeader.descender` value and from the
+`typo_descender`. `win_descent` is computed as the ``-y_min`` for all
+characters in the Windows ANSI character set. `win_descent` is used to
+compute the Windows font height and default line spacing. For platform
+3 encoding 0 fonts, it is the same as ``-TTHeader.y_min``. Windows
+will clip the bitmap of any portion of a glyph that appears below this
+value. Some applications use this value to determine default line
+spacing. This is strongly discouraged. The typographic ascender,
+descender and line gap fields in conjunction with unitsPerEm should be
+used for this purpose. Developers should set this field keeping the
+above factors in mind.
+
+If any clipping is unacceptable, then the value should be set to
+`TT_Header.y_min`.
+
+However, if a developer desires to provide appropriate default line
+spacing using this field, for those applications that continue to use
+this field for doing so (against OpenType recommendations), then the
+value should be set appropriately. In such a case, it may result in
+some glyph bitmaps being clipped.
 """
 
 TT_OS2_x_height = """
-TODO
+This metric specifies the distance between the baseline and the
+approximate height of non-ascending lowercase letters measured in font
+units. This value would normally be specified by a type designer but
+in situations where that is not possible, for example when a legacy
+font is being converted, the value may be set equal to the top of the
+unscaled and unhinted glyph bounding box of the glyph encoded at
+``U+0078`` (``LATIN SMALL LETTER X``). If no glyph is encoded in this
+position the field should be set to 0.
+
+This metric, if specified, can be used in font substitution: the
+`x_height` value of one font can be scaled to approximate the apparent
+size of another.
 """
 
 TT_OS2_cap_height = """
-TODO
+This metric specifies the distance between the baseline and the
+approximate height of uppercase letters measured in font units. This
+value would normally be specified by a type designer but in situations
+where that is not possible, for example when a legacy font is being
+converted, the value may be set equal to the top of the unscaled and
+unhinted glyph bounding box of the glyph encoded at ``U+0048`` (``LATIN
+CAPITAL LETTER H``). If no glyph is encoded in this position the field
+should be set to 0.
+
+This metric, if specified, can be used in systems that specify type
+size by capital height measured in millimeters. It can also be used as
+an alignment metric; the top of a drop capital, for instance, can be
+aligned to the `cap_height` metric of the first line of text.
 """
 
 TT_OS2_default_char = """
-TODO
+Whenever a request is made for a character that is not in the font,
+Windows provides this default character. If the value of this field is
+zero, glyph ID 0 is to be used for the default character otherwise
+this is the Unicode encoding of the glyph that Windows uses as the
+default character. This field cannot represent supplementary character
+values (codepoints greater than ``0xFFFF``), and so applications are
+strongly discouraged from using this field.
 """
 
 TT_OS2_break_char = """
-TODO
+This is the Unicode encoding of the glyph that Windows uses as the
+break character. The break character is used to separate words and
+justify text. Most fonts specify 'space' as the break character. This
+field cannot represent supplementary character values (codepoints
+greater than ``0xFFFF``), and so applications are strongly discouraged
+from using this field.
 """
 
 TT_OS2_max_context = """
-TODO
+The maximum length of a target glyph context for any feature in this
+font. For example, a font which has only a pair kerning feature should
+set this field to 2. If the font also has a ligature feature in which
+the glyph sequence "f f i" is substituted by the ligature "ffi", then
+this field should be set to 3. This field could be useful to
+sophisticated line-breaking engines in determining how far they should
+look ahead to test whether something could change that effects the
+line breaking. For chaining contextual lookups, the length of the
+string (covered glyph) + (input sequence) + (lookahead sequence)
+should be considered.
 """

lib/freetypy/tests/test_face.py

@@ -113,12 +113,13 @@ def test_face_set_transform():
 
 
 def test_kerning():
-    # TODO: Why are we not getting a kerning value here?
     face = ft.Face(vera_path())
+    face.set_char_size(24, 24, 300, 300)
     assert face.face_flags & ft.FACE_FLAG.KERNING
     A = face.get_char_index(ord('A'))
     V = face.get_char_index(ord('V'))
-    assert face.get_kerning(A, V) == (0, 0)
+    assert face.get_kerning(A, V, ft.KERNING.UNSCALED) == (-2.046875, 0.0)
+    assert face.get_kerning(A, V, ft.KERNING.DEFAULT) == (-6, 0)
 
 
 def test_get_glyph_name():

lib/freetypy/tests/test_layout.py

@@ -35,7 +35,7 @@
 
 def test_layout():
     face = ft.Face(vera_path())
-    face.set_charmap(0)
+    face.select_charmap(ft.ENCODING.UNICODE)
     face.set_char_size(24.0)
 
     layout = ft.Layout(
@@ -51,3 +51,13 @@ def test_layout():
         55, 75, 72, 3, 84, 88, 76, 70, 78, 3, 69, 85, 82, 90, 81, 3,
         73, 82, 91, 3, 77, 88, 80, 83, 72, 71, 3, 82, 89, 72, 85, 3,
         87, 75, 72, 3, 79, 68, 93, 92, 3, 71, 82, 74]
+
+
+@raises(ValueError)
+def test_layout_wrong_encoding():
+    face = ft.Face(vera_path())
+    face.set_charmap(0)
+    face.set_char_size(24.0)
+
+    layout = ft.Layout(
+        face, "The quick brown fox jumped over the lazy dog")

lib/freetypy/tests/test_truetype.py

@@ -48,8 +48,6 @@ def test_tt_header():
     assert x.flags == 31
     assert x.font_direction == 1
     assert x.font_revision == 2.0
-    assert x.glyph_data_format == 0
-    assert x.index_to_loc_format == 0
     assert x.lowest_rec_ppem == 8
     assert x.mac_style == 0
     assert x.magic_number == 0x5f0f3cf5

lib/freetypy/tests/util.py

@@ -33,9 +33,6 @@
 
 from __future__ import print_function, unicode_literals, absolute_import
 
-import functools
-import os
-
 
 from nose.tools import raises
 

lib/freetypy/util.py

@@ -38,7 +38,7 @@
 import sys
 
 
-__all__ = ['vera_path', 'draw_glyph_to_console']
+__all__ = ['vera_path', 'bitmap_to_ascii']
 
 
 def vera_path():
@@ -49,7 +49,7 @@ def vera_path():
     return os.path.join(os.path.dirname(__file__), 'data', 'Vera.ttf')
 
 
-def glyph_to_ascii(a):
+def bitmap_to_ascii(a):
     """
     Converts a single glyph to a string with an ASCII drawing of that
     glyph.

setup.py

@@ -31,14 +31,10 @@
 # as representing official policies, either expressed or implied, of
 # the FreeBSD Project.
 
-# TODO: PEP8-ify identifiers
-
 from __future__ import print_function, absolute_import
 
 from distutils.core import setup, Extension
 import glob
-import os
-import subprocess
 import sys
 
 sys.path.insert(0, 'buildext')

src/charmap.c

@@ -35,8 +35,6 @@ either expressed or implied, of the FreeBSD Project.
 #include FT_TRUETYPE_TABLES_H
 #include FT_TRUETYPE_IDS_H
 
-/* TODO: Add a nice repr here */
-
 
 #define CHARMAP_GETTER(name, type) GETTER(name, type, FT_CharMapRec, Py_CharMap);
 #define CHARMAP_METHOD(name) DEF_METHOD(name, CharMap)
@@ -217,6 +215,29 @@ static PyMethodDef Py_CharMap_methods[] = {
 };
 
 
+/****************************************************************************
+ repr
+*/
+
+
+static PyObject *
+Py_CharMap_repr(Py_CharMap *self)
+{
+    PyObject *encoding;
+    PyObject *repr;
+
+    encoding = encoding_get(self, NULL);
+    if (encoding == NULL) {
+        return NULL;
+    }
+
+    repr = PyUnicode_FromFormat("<freetypy.CharMap '%s'>", encoding);
+
+    Py_DECREF(encoding);
+    return repr;
+}
+
+
 /****************************************************************************
  Setup
 */
@@ -252,6 +273,7 @@ int setup_CharMap(PyObject *m)
         .tp_name = "freetypy.CharMap",
         .tp_basicsize = sizeof(Py_CharMap),
         .tp_doc = doc_CharMap__init__,
+        .tp_repr = (unaryfunc)Py_CharMap_repr,
         .tp_getset = Py_CharMap_getset,
         .tp_methods = Py_CharMap_methods,
         .tp_init = (initproc)Py_CharMap_init,