From 32f8735aa5f3c22f6beea5dea6a74e25c215e38b Mon Sep 17 00:00:00 2001
From: Cosimo Lupo <cosimo@anthrotype.com>
Date: Sun, 21 Oct 2018 18:26:26 +0100
Subject: [PATCH] README: mention extras and ufoLib dependencies

---
 README.rst | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.rst b/README.rst
index 79f1e3b25..6e703ae5c 100644
--- a/README.rst
+++ b/README.rst
@@ -164,6 +164,38 @@ 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 by some of its modules, which
 are needed to unlock optional features.
+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.
+
+- ``Lib/fontTools/misc/etree.py``
+
+  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 <https://http://lxml.de>`__. The latter is preferred whenever present,
+  as it is generally faster and more secure.
+
+  *Extra:* ``lxml``
+
+- ``Lib/fontTools/ufoLib``
+
+  Package for reading and writing UFO source files; it requires:
+
+  - `fs <https://pypi.org/pypi/fs`__: (aka ``pyfilesystem2``) filesystem
+    abstraction layer.
+
+  - `enum34 <https://pypi.org/pypi/enum34`__: backport for the built-in ``enum``
+    module (only required on Python < 3.4).
+
+  *Extra:* ``ufo``
 
 -  ``Lib/fontTools/ttLib/woff2.py``
 
@@ -172,6 +204,8 @@ are needed to unlock optional features.
    -  `brotli <https://pypi.python.org/pypi/Brotli>`__: Python bindings of
       the Brotli compression library.
 
+  *Extra:* ``woff``
+
 -  ``Lib/fontTools/ttLib/sfnt.py``
 
    To better compress WOFF 1.0 web fonts, the following module can be used
@@ -180,6 +214,8 @@ are needed to unlock optional features.
    -  `zopfli <https://pypi.python.org/pypi/zopfli>`__: Python bindings of
       the Zopfli compression library.
 
+  *Extra:* ``woff``
+
 -  ``Lib/fontTools/unicode.py``
 
    To display the Unicode character names when dumping the ``cmap`` table
@@ -192,6 +228,8 @@ are needed to unlock optional features.
       Unicode version 9.0. Note this is not necessary if you use Python 3.6
       as the latter already comes with an up-to-date ``unicodedata``.
 
+  *Extra:* ``unicode``
+
 -  ``Lib/fontTools/varLib/interpolatable.py``
 
    Module for finding wrong contour/component order between different masters.
@@ -205,6 +243,8 @@ are needed to unlock optional features.
    *  `munkres <https://pypi.python.org/pypi/munkres>`__: a pure-Python
       module that implements the Hungarian or Kuhn-Munkres algorithm.
 
+  *Extra:* ``interpolatable``
+
 -  ``Lib/fontTools/misc/symfont.py``
 
    Advanced module for symbolic font statistics analysis; it requires:
@@ -212,6 +252,8 @@ are needed to unlock optional features.
    *  `sympy <https://pypi.python.org/pypi/sympy>`__: the Python library for
       symbolic mathematics.
 
+   *Extra:* ``symfont``
+
 -  ``Lib/fontTools/t1Lib.py``
 
    To get the file creator and type of Macintosh PostScript Type 1 fonts
@@ -221,6 +263,8 @@ are needed to unlock optional features.
    *  `xattr <https://pypi.python.org/pypi/xattr>`__: Python wrapper for
       extended filesystem attributes (macOS platform only).
 
+   *Extra:* ``type1``
+
 -  ``Lib/fontTools/pens/cocoaPen.py``
 
    Pen for drawing glyphs with Cocoa ``NSBezierPath``, requires: