diff --git a/Doc/source/index.rst b/Doc/source/index.rst index e9ea2806f..79aae28de 100644 --- a/Doc/source/index.rst +++ b/Doc/source/index.rst @@ -31,165 +31,59 @@ See the Optional Requirements section below for details about module-specific de Utilities --------- -Commands for merging and subsetting fonts are also available:: +fontTools installs four command-line utilities: - pyftmerge - pyftsubset +- ``pyftmerge``, a tool for merging fonts; see :py:mod:`fontTools.merge` +- ``pyftsubset``, a tool for subsetting fonts; see :py:mod:`fontTools.subset` +- ``ttx``, a tool for converting between OpenType binary fonts (OTF) and an XML representation (TTX); see :py:mod:`fontTools.ttx` +- ``fonttools``, a "meta-tool" for accessing other components of the fontTools family. -Please see the :py:mod:`fontTools.merge` and :py:mod:`fontTools.subset` documentation for additional information about these tools. +This last utility takes a subcommand, which could be one of: + +- ``cu2qu``: Convert a UFO font with cubic curves to quadratic curves +- ``feaLib``: Add features from a feature file (.fea) into a OTF font +- ``mtiLib``: Convert Monotype FontDame layout files to TTX +- ``subset``: OpenType font subsetter and optimizer +- ``varLib``: Build a variable font from a designspace file and masters Libraries --------- -XXX +The main library you will want to access when using fontTools for font +engineering is likely to be :py:mod:`fontTools.ttLib`, which is the package +for handling TrueType/OpenType fonts. However, there are many other +libraries in the fontTools suite: + +- :py:mod:`fontTools.afmLib`: Module for reading and writing AFM files +- :py:mod:`fontTools.agl`: Access to the Adobe Glyph List +- :py:mod:`fontTools.cffLib`: Read/write tools for Adobe CFF fonts +- :py:mod:`fontTools.colorLib`: Module for handling colors in CPAL/COLR fonts +- :py:mod:`fontTools.cu2qu`: Module for cubic to quadratic conversion +- :py:mod:`fontTools.designspaceLib`: Read and write designspace files +- :py:mod:`fontTools.encodings`: Support for font-related character encodings +- :py:mod:`fontTools.feaLib`: Read and read AFDKO feature files +- :py:mod:`fontTools.fontBuilder`: Construct TTF/OTF fonts from scratch +- :py:mod:`fontTools.merge`: Tools for merging font files +- :py:mod:`fontTools.pens`: Various classes for manipulating glyph outlines +- :py:mod:`fontTools.subset`: OpenType font subsetting and optimization +- :py:mod:`fontTools.svgLib.path`: Library for drawing SVG paths onto glyphs +- :py:mod:`fontTools.t1Lib`: Tools for PostScript Type 1 fonts (Python2 only) +- :py:mod:`fontTools.ttx`: Module for converting between OTF and XML representation +- :py:mod:`fontTools.ufoLib`: Module for reading and writing UFO files +- :py:mod:`fontTools.unicodedata`: Convert between Unicode and OpenType script information +- :py:mod:`fontTools.varLib`: Module for dealing with 'gvar'-style font variations +- :py:mod:`fontTools.voltLib`: Module for dealing with Visual OpenType Layout Tool (VOLT) files A selection of sample Python programs using these libaries can be found in the `Snippets directory `_ of the fontTools repository. -Optional Requirements +Optional Dependencies --------------------- The fontTools package currently has no (required) external dependencies besides the modules included in the Python Standard Library. However, a few extra dependencies are required to unlock optional features -in some of the library modules. - -The fonttools PyPI distribution also supports so-called "extras", i.e. a -set of keywords that describe a group of additional dependencies, which can be -used when installing via pip, or when specifying a requirement. -For example: - -.. code:: sh - - pip install fonttools[ufo,lxml,woff,unicode] - -This command will install fonttools, as well as the optional dependencies that -are required to unlock the extra features named "ufo", etc. - -.. note:: - - Optional dependencies are detailed by module in the list below with the ``Extra`` setting that automates ``pip`` dependency installation when this is supported. - - - -:py:mod:`fontTools.misc.etree` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The module exports a ElementTree-like API for reading/writing XML files, and allows to use as the backend either the built-in ``xml.etree`` module or `lxml `__. The latter is preferred whenever present, as it is generally faster and more secure. - -*Extra:* ``lxml`` - - -:py:mod:`fontTools.ufoLib` -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Package for reading and writing UFO source files; it requires: - -* `fs `__: (aka ``pyfilesystem2``) filesystem abstraction layer. - -* `enum34 `__: backport for the built-in ``enum`` module (only required on Python < 3.4). - -*Extra:* ``ufo`` - - -:py:mod:`fontTools.ttLib.woff2` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Module to compress/decompress WOFF 2.0 web fonts; it requires: - -* `brotli `__: Python bindings of the Brotli compression library. - -*Extra:* ``woff`` - - -:py:mod:`fontTools.unicode` -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To display the Unicode character names when dumping the ``cmap`` table -with ``ttx`` we use the ``unicodedata`` module in the Standard Library. -The version included in there varies between different Python versions. -To use the latest available data, you can install: - -* `unicodedata2 `__: ``unicodedata`` backport for Python 2.7 - and 3.x updated to the latest Unicode version 12.0. Note this is not necessary if you use Python 3.8 - as the latter already comes with an up-to-date ``unicodedata``. - -*Extra:* ``unicode`` - - -:py:mod:`fontTools.varLib.interpolatable` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Module for finding wrong contour/component order between different masters. -It requires one of the following packages in order to solve the so-called -"minimum weight perfect matching problem in bipartite graphs", or -the Assignment problem: - -* `scipy `__: the Scientific Library for Python, which internally - uses `NumPy `__ arrays and hence is very fast; -* `munkres `__: a pure-Python module that implements the Hungarian - or Kuhn-Munkres algorithm. - -*Extra:* ``interpolatable`` - - -:py:mod:`fontTools.varLib.plot` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Module for visualizing DesignSpaceDocument and resulting VariationModel. - -* `matplotlib `__: 2D plotting library. - -*Extra:* ``plot`` - - -:py:mod:`fontTools.misc.symfont` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Advanced module for symbolic font statistics analysis; it requires: - -* `sympy `__: the Python library for symbolic mathematics. - -*Extra:* ``symfont`` - - -:py:mod:`fontTools.t1Lib` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -To get the file creator and type of Macintosh PostScript Type 1 fonts -on Python 3 you need to install the following module, as the old ``MacOS`` -module is no longer included in Mac Python: - -* `xattr `__: Python wrapper for extended filesystem attributes - (macOS platform only). - -*Extra:* ``type1`` - - -:py:mod:`fontTools.pens.cocoaPen` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Pen for drawing glyphs with Cocoa ``NSBezierPath``, requires: - -* `PyObjC `__: the bridge between Python and the Objective-C - runtime (macOS platform only). - - -:py:mod:`fontTools.pens.qtPen` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Pen for drawing glyphs with Qt's ``QPainterPath``, requires: - -* `PyQt5 `__: Python bindings for the Qt cross platform UI and - application toolkit. - - -:py:mod:`fontTools.pens.reportLabPen` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Pen to drawing glyphs as PNG images, requires: - -* `reportlab `__: Python toolkit for generating PDFs and - graphics. +in some of the library modules. See the :doc:`optional requirements <./optional>` +page for more information. Developer information --------------------- diff --git a/Doc/source/optional.rst b/Doc/source/optional.rst new file mode 100644 index 000000000..09376a26a --- /dev/null +++ b/Doc/source/optional.rst @@ -0,0 +1,140 @@ +Optional Dependencies +===================== + +The fonttools PyPI distribution also supports so-called "extras", i.e. a +set of keywords that describe a group of additional dependencies, which can be +used when installing via pip, or when specifying a requirement. +For example: + +.. code:: sh + + pip install fonttools[ufo,lxml,woff,unicode] + +This command will install fonttools, as well as the optional dependencies that +are required to unlock the extra features named "ufo", etc. + +.. note:: + + Optional dependencies are detailed by module in the list below with the ``Extra`` setting that automates ``pip`` dependency installation when this is supported. + + + +:py:mod:`fontTools.misc.etree` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The module exports a ElementTree-like API for reading/writing XML files, and allows to use as the backend either the built-in ``xml.etree`` module or `lxml `__. The latter is preferred whenever present, as it is generally faster and more secure. + +*Extra:* ``lxml`` + + +:py:mod:`fontTools.ufoLib` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Package for reading and writing UFO source files; it requires: + +* `fs `__: (aka ``pyfilesystem2``) filesystem abstraction layer. + +* `enum34 `__: backport for the built-in ``enum`` module (only required on Python < 3.4). + +*Extra:* ``ufo`` + + +:py:mod:`fontTools.ttLib.woff2` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Module to compress/decompress WOFF 2.0 web fonts; it requires: + +* `brotli `__: Python bindings of the Brotli compression library. + +*Extra:* ``woff`` + + +:py:mod:`fontTools.unicode` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To display the Unicode character names when dumping the ``cmap`` table +with ``ttx`` we use the ``unicodedata`` module in the Standard Library. +The version included in there varies between different Python versions. +To use the latest available data, you can install: + +* `unicodedata2 `__: ``unicodedata`` backport for Python 2.7 + and 3.x updated to the latest Unicode version 12.0. Note this is not necessary if you use Python 3.8 + as the latter already comes with an up-to-date ``unicodedata``. + +*Extra:* ``unicode`` + + +:py:mod:`fontTools.varLib.interpolatable` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Module for finding wrong contour/component order between different masters. +It requires one of the following packages in order to solve the so-called +"minimum weight perfect matching problem in bipartite graphs", or +the Assignment problem: + +* `scipy `__: the Scientific Library for Python, which internally + uses `NumPy `__ arrays and hence is very fast; +* `munkres `__: a pure-Python module that implements the Hungarian + or Kuhn-Munkres algorithm. + +*Extra:* ``interpolatable`` + + +:py:mod:`fontTools.varLib.plot` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Module for visualizing DesignSpaceDocument and resulting VariationModel. + +* `matplotlib `__: 2D plotting library. + +*Extra:* ``plot`` + + +:py:mod:`fontTools.misc.symfont` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Advanced module for symbolic font statistics analysis; it requires: + +* `sympy `__: the Python library for symbolic mathematics. + +*Extra:* ``symfont`` + + +:py:mod:`fontTools.t1Lib` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +To get the file creator and type of Macintosh PostScript Type 1 fonts +on Python 3 you need to install the following module, as the old ``MacOS`` +module is no longer included in Mac Python: + +* `xattr `__: Python wrapper for extended filesystem attributes + (macOS platform only). + +*Extra:* ``type1`` + + +:py:mod:`fontTools.pens.cocoaPen` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pen for drawing glyphs with Cocoa ``NSBezierPath``, requires: + +* `PyObjC `__: the bridge between Python and the Objective-C + runtime (macOS platform only). + + +:py:mod:`fontTools.pens.qtPen` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pen for drawing glyphs with Qt's ``QPainterPath``, requires: + +* `PyQt5 `__: Python bindings for the Qt cross platform UI and + application toolkit. + + +:py:mod:`fontTools.pens.reportLabPen` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pen to drawing glyphs as PNG images, requires: + +* `reportlab `__: Python toolkit for generating PDFs and + graphics. diff --git a/README.rst b/README.rst index dc961c2c3..7a3ff26b0 100644 --- a/README.rst +++ b/README.rst @@ -11,6 +11,9 @@ What is this? licence `__. | Among other things this means you can use it free of charge. +`User documentation ` and +`developer documentation ` is available at `Read the Docs `. + Installation ~~~~~~~~~~~~ @@ -54,112 +57,6 @@ Python 3 `venv `__ module. # install in 'editable' mode pip install -e . -TTX – From OpenType and TrueType to XML and Back -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once installed you can use the ``ttx`` command to convert binary font -files (``.otf``, ``.ttf``, etc) to the TTX XML format, edit them, and -convert them back to binary format. TTX files have a .ttx file -extension. - -.. code:: sh - - ttx /path/to/font.otf - ttx /path/to/font.ttx - -The TTX application can be used in two ways, depending on what -platform you run it on: - -- As a command line tool (Windows/DOS, Unix, macOS) -- By dropping files onto the application (Windows, macOS) - -TTX detects what kind of files it is fed: it will output a ``.ttx`` file -when it sees a ``.ttf`` or ``.otf``, and it will compile a ``.ttf`` or -``.otf`` when the input file is a ``.ttx`` file. By default, the output -file is created in the same folder as the input file, and will have the -same name as the input file but with a different extension. TTX will -*never* overwrite existing files, but if necessary will append a unique -number to the output filename (before the extension) such as -``Arial#1.ttf`` - -When using TTX from the command line there are a bunch of extra options. -These are explained in the help text, as displayed when typing -``ttx -h`` at the command prompt. These additional options include: - -- specifying the folder where the output files are created -- specifying which tables to dump or which tables to exclude -- merging partial ``.ttx`` files with existing ``.ttf`` or ``.otf`` - files -- listing brief table info instead of dumping to ``.ttx`` -- splitting tables to separate ``.ttx`` files -- disabling TrueType instruction disassembly - -The TTX file format -------------------- - -The following tables are currently supported: - -.. begin table list -.. code:: - - BASE, CBDT, CBLC, CFF, CFF2, COLR, CPAL, DSIG, EBDT, EBLC, FFTM, - Feat, GDEF, GMAP, GPKG, GPOS, GSUB, Glat, Gloc, HVAR, JSTF, LTSH, - MATH, META, MVAR, OS/2, SING, STAT, SVG, Silf, Sill, TSI0, TSI1, - TSI2, TSI3, TSI5, TSIB, TSID, TSIJ, TSIP, TSIS, TSIV, TTFA, VDMX, - VORG, VVAR, ankr, avar, bsln, cidg, cmap, cvar, cvt, feat, fpgm, - fvar, gasp, gcid, glyf, gvar, hdmx, head, hhea, hmtx, kern, lcar, - loca, ltag, maxp, meta, mort, morx, name, opbd, post, prep, prop, - sbix, trak, vhea and vmtx -.. end table list - -Other tables are dumped as hexadecimal data. - -TrueType fonts use glyph indices (GlyphIDs) to refer to glyphs in most -places. While this is fine in binary form, it is really hard to work -with for humans. Therefore we use names instead. - -The glyph names are either extracted from the ``CFF`` table or the -``post`` table, or are derived from a Unicode ``cmap`` table. In the -latter case the Adobe Glyph List is used to calculate names based on -Unicode values. If all of these methods fail, names are invented based -on GlyphID (eg ``glyph00142``) - -It is possible that different glyphs use the same name. If this happens, -we force the names to be unique by appending ``#n`` to the name (``n`` -being an integer number.) The original names are being kept, so this has -no influence on a "round tripped" font. - -Because the order in which glyphs are stored inside the binary font is -important, we maintain an ordered list of glyph names in the font. - -Other Tools -~~~~~~~~~~~ - -Commands for merging and subsetting fonts are also available: - -.. code:: sh - - pyftmerge - pyftsubset - -fontTools Python Module -~~~~~~~~~~~~~~~~~~~~~~~ - -The fontTools Python module provides a convenient way to -programmatically edit font files. - -.. code:: py - - >>> from fontTools.ttLib import TTFont - >>> font = TTFont('/path/to/font.ttf') - >>> font - - >>> - -A selection of sample Python programs is in the -`Snippets `__ -directory. - Optional Requirements --------------------- @@ -297,64 +194,6 @@ are required to unlock the extra features named "ufo", etc. * `reportlab `__: Python toolkit for generating PDFs and graphics. -Testing -~~~~~~~ - -To run the test suite, you need to install `pytest `__. -When you run the ``pytest`` command, the tests will run against the -installed ``fontTools`` package, or the first one found in the -``PYTHONPATH``. - -You can also use `tox `__ to -automatically run tests on different Python versions in isolated virtual -environments. - -.. code:: sh - - pip install tox - tox - -Note that when you run ``tox`` without arguments, the tests are executed -for all the environments listed in tox.ini's ``envlist``. In our case, -this includes Python 3.6 and 3.7, so for this to work the ``python3.6`` -and ``python3.7`` executables must be available in your ``PATH``. - -You can specify an alternative environment list via the ``-e`` option, -or the ``TOXENV`` environment variable: - -.. code:: sh - - tox -e py36 - TOXENV="py36-cov,htmlcov" tox - -Development Community -~~~~~~~~~~~~~~~~~~~~~ - -TTX/FontTools development is ongoing in an active community of -developers, that includes professional developers employed at major -software corporations and type foundries as well as hobbyists. - -Feature requests and bug reports are always welcome at -https://github.com/fonttools/fonttools/issues/ - -The best place for discussions about TTX from an end-user perspective as -well as TTX/FontTools development is the -https://groups.google.com/d/forum/fonttools mailing list. There is also -a development https://groups.google.com/d/forum/fonttools-dev mailing -list for continuous integration notifications. You can also email Behdad -privately at behdad@behdad.org - -History -~~~~~~~ - -The fontTools project was started by Just van Rossum in 1999, and was -maintained as an open source project at -http://sourceforge.net/projects/fonttools/. In 2008, Paul Wise (pabs3) -began helping Just with stability maintenance. In 2013 Behdad Esfahbod -began a friendly fork, thoroughly reviewing the codebase and making -changes at https://github.com/behdad/fonttools to add new features and -support for new font formats. - Acknowledgements ~~~~~~~~~~~~~~~~