diff --git a/Doc/source/ttLib/index.rst b/Doc/source/ttLib/index.rst index 656148e5d..0f5e3946a 100644 --- a/Doc/source/ttLib/index.rst +++ b/Doc/source/ttLib/index.rst @@ -2,7 +2,13 @@ ttLib: Read and write OpenType and TrueType fonts ################################################# -Most users of the fontTools library will be using it to generate or manipulate +.. contents:: On this page: + :local: + +.. rubric:: Overview: + :heading-level: 2 + +Most users of the :mod:`fontTools` library will be using it to generate or manipulate OpenType and TrueType fonts. (FontTools initially only supported TrueType fonts, gaining OpenType support in version 2.0, and so uses the ``tt`` prefix to refer to both kinds of font. Because of this we will refer to both as "TrueType fonts" @@ -10,14 +16,46 @@ unless we need to make a distinction.) The main entry point for such operations is the :py:mod:`fontTools.ttLib.ttFont` module, but other modules also provide useful functionality for handling OpenType -fonts. +fonts: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 ttFont + +:mod:`.ttLib` supports fonts with TrueType-flavored glyphs (i.e., with +a ``glyf`` table), with PostScript-flavored glyphs (i.e., ``CFF`` or +``CFF2`` tables), and with all of the glyph formats used for color fonts +(``CBDT``, ``COLR``, ``sbix``, and ``SVG``). Static and variable fonts +are both supported. + + +Command-line utilities +---------------------- + +:mod:`.ttLib` includes two modules that provide command-line operations: + +.. toctree:: + :maxdepth: 1 + + removeOverlaps + scaleUpem + + +Supporting modules +------------------ + +It also contains helper modules that enable lower-level +functionality. In most cases, users will not need to access these +modules directly: + +.. toctree:: + :maxdepth: 1 + ttCollection + ttGlyphSet macUtils + reorderGlyphs sfnt standardGlyphOrder tables diff --git a/Doc/source/ttLib/macUtils.rst b/Doc/source/ttLib/macUtils.rst index 356a911b2..81413301f 100644 --- a/Doc/source/ttLib/macUtils.rst +++ b/Doc/source/ttLib/macUtils.rst @@ -1,8 +1,7 @@ -######## -macUtils -######## +########################################## +macUtils: Access fonts in Mac file formats +########################################## .. automodule:: fontTools.ttLib.macUtils - :inherited-members: :members: :undoc-members: diff --git a/Doc/source/ttLib/removeOverlaps.rst b/Doc/source/ttLib/removeOverlaps.rst new file mode 100644 index 000000000..83e99922b --- /dev/null +++ b/Doc/source/ttLib/removeOverlaps.rst @@ -0,0 +1,13 @@ +############################################################## +removeOverlaps: Tools to remove overlapping contours in glyphs +############################################################## + +.. rubric:: Overview + :heading-level: 2 + +The :mod:`fontTools.ttLib.removeOverlaps` module is a helper for +:mod:`fontTools.ttLib`. + +.. automodule:: fontTools.ttLib.removeOverlaps + :members: + :undoc-members: diff --git a/Doc/source/ttLib/reorderGlyphs.rst b/Doc/source/ttLib/reorderGlyphs.rst new file mode 100644 index 000000000..95635588d --- /dev/null +++ b/Doc/source/ttLib/reorderGlyphs.rst @@ -0,0 +1,13 @@ +######################################################## +reorderGlyphs: Functions to reorder the glyphs in a font +######################################################## + +.. rubric:: Overview + :heading-level: 2 + +The :mod:`fontTools.ttLib.reorderGlyphs` module is a helper for +:mod:`fontTools.ttLib`. + +.. automodule:: fontTools.ttLib.reorderGlyphs + :members: + :undoc-members: diff --git a/Doc/source/ttLib/scaleUpem.rst b/Doc/source/ttLib/scaleUpem.rst new file mode 100644 index 000000000..4ac16b2d2 --- /dev/null +++ b/Doc/source/ttLib/scaleUpem.rst @@ -0,0 +1,13 @@ +########################################################### +scaleUpem: Tools to change the units-per-Em value in a font +########################################################### + +.. rubric:: Overview + :heading-level: 2 + +The :mod:`fontTools.ttLib.scaleUpem` module is a helper for +:mod:`fontTools.ttLib`. + +.. automodule:: fontTools.ttLib.scaleUpem + :members: + :undoc-members: diff --git a/Doc/source/ttLib/sfnt.rst b/Doc/source/ttLib/sfnt.rst index 29566ab74..a1fa433c3 100644 --- a/Doc/source/ttLib/sfnt.rst +++ b/Doc/source/ttLib/sfnt.rst @@ -1,8 +1,7 @@ -#### -sfnt -#### +######################################### +sfnt: Read and write the SFNT file format +######################################### .. automodule:: fontTools.ttLib.sfnt - :inherited-members: :members: :undoc-members: diff --git a/Doc/source/ttLib/standardGlyphOrder.rst b/Doc/source/ttLib/standardGlyphOrder.rst index ca2557bf3..6cb7b4e0d 100644 --- a/Doc/source/ttLib/standardGlyphOrder.rst +++ b/Doc/source/ttLib/standardGlyphOrder.rst @@ -1,9 +1,8 @@ -################## -standardGlyphOrder -################## +########################################################### +standardGlyphOrder: Interface with the Standard Glyph Order +########################################################### .. automodule:: fontTools.ttLib.standardGlyphOrder - :inherited-members: :members: :undoc-members: diff --git a/Doc/source/ttLib/tables/TupleVariation.rst b/Doc/source/ttLib/tables/TupleVariation.rst index afeff5c0c..5e267e13b 100644 --- a/Doc/source/ttLib/tables/TupleVariation.rst +++ b/Doc/source/ttLib/tables/TupleVariation.rst @@ -2,6 +2,8 @@ OpenType variations helper module ################################# +.. currentmodule:: fontTools.ttLib.tables.TupleVariation + .. rubric:: Overview: :heading-level: 2 diff --git a/Doc/source/ttLib/ttCollection.rst b/Doc/source/ttLib/ttCollection.rst index 0ca4ebd0d..b19fcdbe8 100644 --- a/Doc/source/ttLib/ttCollection.rst +++ b/Doc/source/ttLib/ttCollection.rst @@ -1,8 +1,15 @@ -############ -ttCollection -############ +################################################################ +ttCollection: Access fonts within a TrueType/OpenType Collection +################################################################ + +.. rubric:: Overview + :heading-level: 2 + +The :mod:`fontTools.ttLib.ttCollection` module is a helper for +:mod:`fontTools.ttLib`. It supports the reading of TrueType and +OpenType `Collection `_ files (\*.ttc, \*.otc) so that each member font in +the collection is accessible as a :class:`.TTFont` instance. .. automodule:: fontTools.ttLib.ttCollection - :inherited-members: :members: - :undoc-members: \ No newline at end of file + :undoc-members: diff --git a/Doc/source/ttLib/ttFont.rst b/Doc/source/ttLib/ttFont.rst index d094b29dc..7c7a60da6 100644 --- a/Doc/source/ttLib/ttFont.rst +++ b/Doc/source/ttLib/ttFont.rst @@ -1,17 +1,99 @@ -############################################## -ttFont: Read/write OpenType and TrueType fonts -############################################## +#################################### +ttFont: Read and write font contents +#################################### + +.. contents:: On this page: + :local: + +.. rubric:: Overview + :heading-level: 2 + +:mod:`.ttLib.ttFont` is the primary fontTools interface for +inspecting, constructing, or deconstructing TrueType and OpenType +fonts. + +The :class:`fontTools.ttLib.ttFont.TTFont` class provides access to +font-level data, including font metrics, substitution and positioning +features, and metadata, through a set of :doc:`table converters +`. A :class:`.TTFont` may be instantiated from a single +font file, or it may be a member of a +:class:`.TTCollection`. :class:`.TTFont` objects can also be +constructed from scratch. + + +glyphSets and ttGlyphs +---------------------- + +In addition to font-wide data, :mod:`.ttLib.ttFont` provides access to +individual glyphs through a :class:`.TTFont` instance's +``.glyphSet[]`` attribute. A ``.glyphSet`` is a dict-like object that is +indexed by glyph names. Users can use the glyphSet to interact with +each glyph's contours, components, points, and glyph metrics. + +Informally, some fontTools code or documentation will make reference to +the individual glyphs in a ``.glyphSet`` as a "ttGlyph" or the +like. This is convenient terminology, particularly for +discussion. However, it is important to note that there is not a +"ttGlyph" class. Instead, the ``.glyphSet`` attribute of a +:class:`.TTFont` serves as an abstraction layer that provides a +uniform interface to the glyphs, regardless of whether the +:class:`.TTFont` instance in use comes from a font file with +TrueType-flavored glyphs (and, therefore, has a `glyf` table +containing glyph contours) or a font with PostScript-flavored outlines +(and, therefore, with a ``CFF`` or ``CFF2`` table containing the glyph +contours). + +Regardless of the flavor, each "ttGlyph" entry in the ``.glyphSet`` +includes the corresponding Bezier outlines and components from the +``glyf`` or ``CFF``/``CFF2`` table and the glyph's metrics. Horizontal +metrics are drawn from the font's ``hmtx`` table, and vertical metrics +(if any) are drawn from the ``vmtx`` table. These attributes are: + + width + The advance width of the glyph + + lsb + The left sidebearing of the glyph + + height + (For vertical-layout fonts) The advance height of the glyph + + tsb + (for vertical-layout fonts) The top sidebearing of the glyph + +Note that these attributes do not describe the bounding box of the +glyph filled shape, because the filled area might include negative +coordinate values or extend beyond the advance width due to overhang. + +The bounds of the glyph are accessible as ``xMin``, ``xMax``, +``yMin``, and ``yMax`` attributes. + +For implementation details regarding the different flavors of +"ttGlyph", see the :doc:`ttGlyphSet ` +documentation. + +These glyph objects also implement the :doc:`Pen Protocol +` by providing ``.draw()`` and ``.drawPoints()`` +methods. See the :doc:`pens ` package documenation +for more. + + +Package contents +---------------- + .. autoclass:: fontTools.ttLib.ttFont.TTFont - :inherited-members: :members: + :undoc-members: + + .. autoclass:: fontTools.ttLib.ttFont.GlyphOrder - :inherited-members: :members: :undoc-members: :private-members: + .. automodule:: fontTools.ttLib.ttFont :members: getTableModule, registerCustomTableClass, unregisterCustomTableClass, getCustomTableClass, getClassTag, newTable, tagToIdentifier, identifierToTag, tagToXML, xmlToTag, sortedTagList, reorderFontTables :exclude-members: TTFont, GlyphOrder diff --git a/Doc/source/ttLib/ttGlyphSet.rst b/Doc/source/ttLib/ttGlyphSet.rst new file mode 100644 index 000000000..2bbfc7331 --- /dev/null +++ b/Doc/source/ttLib/ttGlyphSet.rst @@ -0,0 +1,18 @@ +################################################# +ttGlyphSet: GlyphSets returned by a TTFont object +################################################# + +.. rubric:: Overview + :heading-level: 2 + +The :mod:`fontTools.ttLib.ttGlyphSet` module is a helper for +:mod:`fontTools.ttLib`. + +Most users will not need to access this module directly. Instead, the +glyphs in a font are accessible as a ``.glyphSet`` dictionary in a +:class:`TTFont` instance. + +.. automodule:: fontTools.ttLib.ttGlyphSet + :members: + :undoc-members: + :private-members: diff --git a/Doc/source/ttLib/woff2.rst b/Doc/source/ttLib/woff2.rst index 327bb5b26..b7fcb2975 100644 --- a/Doc/source/ttLib/woff2.rst +++ b/Doc/source/ttLib/woff2.rst @@ -1,8 +1,11 @@ -##### -woff2 -##### +################################################ +woff2: Read and write the WOFF2 font file format +################################################ + +Note also that :mod:`woff2` supports some :doc:`optional ` +external libraries. + .. automodule:: fontTools.ttLib.woff2 - :inherited-members: :members: :undoc-members: diff --git a/Lib/fontTools/ttLib/tables/otTables.py b/Lib/fontTools/ttLib/tables/otTables.py index bc7fbad91..bc70e15be 100644 --- a/Lib/fontTools/ttLib/tables/otTables.py +++ b/Lib/fontTools/ttLib/tables/otTables.py @@ -2226,24 +2226,28 @@ _equivalents = { def fixLookupOverFlows(ttf, overflowRecord): """Either the offset from the LookupList to a lookup overflowed, or an offset from a lookup to a subtable overflowed. - The table layout is: - GPSO/GUSB - Script List - Feature List - LookUpList - Lookup[0] and contents - SubTable offset list - SubTable[0] and contents - ... - SubTable[n] and contents - ... - Lookup[n] and contents - SubTable offset list - SubTable[0] and contents - ... - SubTable[n] and contents + + The table layout is:: + + GPSO/GUSB + Script List + Feature List + LookUpList + Lookup[0] and contents + SubTable offset list + SubTable[0] and contents + ... + SubTable[n] and contents + ... + Lookup[n] and contents + SubTable offset list + SubTable[0] and contents + ... + SubTable[n] and contents + If the offset to a lookup overflowed (SubTableIndex is None) - we must promote the *previous* lookup to an Extension type. + we must promote the *previous* lookup to an Extension type. + If the offset from a lookup to subtable overflowed, then we must promote it to an Extension Lookup type. """ diff --git a/Lib/fontTools/ttLib/tables/otTraverse.py b/Lib/fontTools/ttLib/tables/otTraverse.py index ac9421872..9b624533f 100644 --- a/Lib/fontTools/ttLib/tables/otTraverse.py +++ b/Lib/fontTools/ttLib/tables/otTraverse.py @@ -79,7 +79,8 @@ def bfs_base_table( """Breadth-first search tree of BaseTables. Args: - the root of the tree. + root + the root of the tree. root_accessor (Optional[str]): attribute name for the root table, if any (mostly useful for debugging). skip_root (Optional[bool]): if True, the root itself is not visited, only its diff --git a/Lib/fontTools/ttLib/ttFont.py b/Lib/fontTools/ttLib/ttFont.py index d7bd92bc2..f9b18008a 100644 --- a/Lib/fontTools/ttLib/ttFont.py +++ b/Lib/fontTools/ttLib/ttFont.py @@ -27,6 +27,7 @@ class TTFont(object): they're actually accessed. This means that simple operations can be extremely fast. Example usage: + .. code-block:: pycon >>> @@ -39,8 +40,10 @@ class TTFont(object): >> tt['head'].unitsPerEm 2048 - For details of the objects returned when accessing each table, see :ref:`tables`. + For details of the objects returned when accessing each table, see the + :doc:`tables ` documentation. To add a table to the font, use the :py:func:`newTable` function: + .. code-block:: pycon >>> @@ -50,7 +53,8 @@ class TTFont(object): >> font["OS/2"] = os2 TrueType fonts can also be serialized to and from XML format (see also the - :ref:`ttx` binary): + :doc:`ttx ` binary): + .. code-block:: pycon >>