diff options
Diffstat (limited to 'Doc/source')
| -rw-r--r-- | Doc/source/conf.py | 33 | ||||
| -rw-r--r-- | Doc/source/designspaceLib/index.rst | 22 | ||||
| -rw-r--r-- | Doc/source/designspaceLib/python.rst | 4 | ||||
| -rw-r--r-- | Doc/source/designspaceLib/scripting.rst | 19 | ||||
| -rw-r--r-- | Doc/source/designspaceLib/xml.rst | 125 | ||||
| -rw-r--r-- | Doc/source/developer.rst | 4 | ||||
| -rw-r--r-- | Doc/source/index.rst | 13 | ||||
| -rw-r--r-- | Doc/source/voltLib/index.rst (renamed from Doc/source/voltLib.rst) | 11 | ||||
| -rw-r--r-- | Doc/source/voltLib/voltToFea.rst | 8 |
9 files changed, 175 insertions, 64 deletions
diff --git a/Doc/source/conf.py b/Doc/source/conf.py index b95119db..982af803 100644 --- a/Doc/source/conf.py +++ b/Doc/source/conf.py @@ -30,14 +30,17 @@ needs_sphinx = "1.3" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.napoleon", "sphinx.ext.coverage", "sphinx.ext.autosectionlabel"] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.coverage", + "sphinx.ext.autosectionlabel", +] autodoc_mock_imports = ["gtk", "reportlab"] -autodoc_default_options = { - 'members': True, - 'inherited-members': True -} +autodoc_default_options = {"members": True, "inherited-members": True} # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -52,9 +55,11 @@ source_suffix = ".rst" master_doc = "index" # General information about the project. -project = u"fontTools" -copyright = u"2020, Just van Rossum, Behdad Esfahbod, and the fontTools Authors. CC BY-SA 4.0" -author = u"Just van Rossum, Behdad Esfahbod, and the fontTools Authors" +project = "fontTools" +copyright = ( + "2020, Just van Rossum, Behdad Esfahbod, and the fontTools Authors. CC BY-SA 4.0" +) +author = "Just van Rossum, Behdad Esfahbod, and the fontTools Authors" # HTML page title html_title = "fontTools Documentation" @@ -64,9 +69,9 @@ html_title = "fontTools Documentation" # built documents. # # The short X.Y version. -version = u"4.0" +version = "4.0" # The full version, including alpha/beta/rc tags. -release = u"4.0" +release = "4.0" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -142,8 +147,8 @@ latex_documents = [ ( master_doc, "fontTools.tex", - u"fontTools Documentation", - u"Just van Rossum, Behdad Esfahbod et al.", + "fontTools Documentation", + "Just van Rossum, Behdad Esfahbod et al.", "manual", ) ] @@ -153,7 +158,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [(master_doc, "fonttools", u"fontTools Documentation", [author], 1)] +man_pages = [(master_doc, "fonttools", "fontTools Documentation", [author], 1)] # -- Options for Texinfo output ------------------------------------------- @@ -165,7 +170,7 @@ texinfo_documents = [ ( master_doc, "fontTools", - u"fontTools Documentation", + "fontTools Documentation", author, "fontTools", "A library for manipulating fonts, written in Python.", diff --git a/Doc/source/designspaceLib/index.rst b/Doc/source/designspaceLib/index.rst index 5d17dc16..7b8b4878 100644 --- a/Doc/source/designspaceLib/index.rst +++ b/Doc/source/designspaceLib/index.rst @@ -127,20 +127,20 @@ Implementation and differences The designspace format has gone through considerable development. - the format was originally written for MutatorMath. - - the format is now also used in fontTools.varlib. + - the format is now also used in fontTools.varLib. - not all values are be required by all implementations. -Varlib vs. MutatorMath +varLib vs. MutatorMath ---------------------- -There are some differences between the way MutatorMath and fontTools.varlib handle designspaces. +There are some differences between the way MutatorMath and fontTools.varLib handle designspaces. - - Varlib does not support anisotropic interpolations. + - varLib does not support anisotropic interpolations. - MutatorMath will extrapolate over the boundaries of - the axes. Varlib can not (at the moment). - - Varlib requires much less data to define an instance than + the axes. varLib can not (at the moment). + - varLib requires much less data to define an instance than MutatorMath. - - The goals of Varlib and MutatorMath are different, so not all + - The goals of varLib and MutatorMath are different, so not all attributes are always needed. @@ -174,6 +174,14 @@ it can become complex very quickly. So proceed with caution. Version history =============== +Version 5.1 +----------- + +The format was extended to support arbitrary mapping between input and output +designspace locations. The ``<axes>`` elements now can have a ``<mappings>`` +element that specifies such mappings, which when present carries data that is +used to compile to an ``avar`` version 2 table. + Version 5.0 ----------- diff --git a/Doc/source/designspaceLib/python.rst b/Doc/source/designspaceLib/python.rst index 6a43bdcc..c998911c 100644 --- a/Doc/source/designspaceLib/python.rst +++ b/Doc/source/designspaceLib/python.rst @@ -187,10 +187,10 @@ for more information. .. automodule:: fontTools.designspaceLib.split -fontTools.designspaceLib.stat +fontTools.varLib.stat ============================= -.. automodule:: fontTools.designspaceLib.stat +.. automodule:: fontTools.varLib.stat fontTools.designspaceLib.statNames diff --git a/Doc/source/designspaceLib/scripting.rst b/Doc/source/designspaceLib/scripting.rst index 63235eec..52ddbd6e 100644 --- a/Doc/source/designspaceLib/scripting.rst +++ b/Doc/source/designspaceLib/scripting.rst @@ -221,23 +221,6 @@ Saving path = "myprototype.designspace" doc.write(path) -************************ -Reading old designspaces -************************ - -Old designspace files might not contain ``axes`` definitions. This is -how you reconstruct the axes from the extremes of the source locations - -.. code:: python - - doc.checkAxes() - -This is how you check the default font. - -.. code:: python - - doc.checkDefault() - *********** Generating? *********** @@ -251,7 +234,7 @@ You can generate the UFOs with MutatorMath: - Assuming the outline data in the masters is compatible. -Or you can use the file in making a **variable font** with varlib. +Or you can use the file in making a **variable font** with varLib. .. _working_with_v5: diff --git a/Doc/source/designspaceLib/xml.rst b/Doc/source/designspaceLib/xml.rst index 6267b025..4e3492ef 100644 --- a/Doc/source/designspaceLib/xml.rst +++ b/Doc/source/designspaceLib/xml.rst @@ -20,10 +20,15 @@ Overview .. code:: xml <?xml version='1.0' encoding='utf-8'?> - <designspace format="5.0"> + <designspace format="5.1"> <axes> <!-- define axes here --> <axis... /> + <mappings> + <!-- define axis mappings here --> + <!-- New in version 5.1 --> + <mapping... /> + </mappings> </axes> <labels> <!-- define STAT format 4 labels here --> @@ -162,10 +167,17 @@ For a discrete axis: ``<labels>`` element (axis) --------------------------- -The ``<labels>`` element contains one or more ``<label>`` elements. +The ``<labels>`` element contains one or more ``<label>`` elements, and can +indicate this axis' STAT ordering. .. versionadded:: 5.0 +.. rubric:: Attributes + +- ``ordering``: optional, int, default: natural position of this axis in the list + of axes. STAT table field ``axisOrdering`` for this axis. + + See: `OTSpec STAT Axis Record <https://docs.microsoft.com/en-us/typography/opentype/spec/stat#axis-records>`_ ``<label>`` element (axis) .......................... @@ -248,6 +260,64 @@ Example of all axis elements together </axes> +``<mappings>`` element +====================== + +- Define axis mappings. +- Child element of ``axes`` + + + .. versionadded:: 5.1 + + +``<mapping>`` element +--------------------- + +- Defines an axis mapping. +- Child element of ``<mappings>`` + + + .. versionadded:: 5.1 + + +``<input>`` element +................... + +- Defines the input location of an axis mapping. +- Child element of ``<mapping>`` +- Contains one or more ``<dimension>`` elements with designspace locations. + + .. versionadded:: 5.1 + + +``<output>`` element +................... + +- Defines the output location of an axis mapping. +- Child element of ``<mapping>`` +- Contains one or more ``<dimension>`` elements with designspace locations. + + .. versionadded:: 5.1 + + +Example of all mappings elements together +========================================= + +.. code:: xml + + <mappings> + <mapping> + <input> + <dimension name="weight" xvalue="900"/> + <dimension name="width" xvalue="150"/> + </input> + <output> + <dimension name="weight" xvalue="870"/> + </output> + </mapping> + </mappings> + + ================================ ``<labels>`` element (top-level) ================================ @@ -297,7 +367,7 @@ See: `OTSpec STAT Axis value table, format 4 <https://docs.microsoft.com/en-us/t ``<dimension>`` element ....................... -- Child element of ``<location>`` +- Child element of ``<location>``, ``input``, or ``output`` elements .. rubric:: Attributes @@ -387,7 +457,7 @@ glyphname pairs: the glyphs that need to be substituted. For a rule to be trigge - Defines a named rule. - Each ``<rule>`` element contains one or more ``<conditionset>`` elements. -- **Only one** ``<conditionset>`` needs to be true to trigger the rule (logical OR). +- **Only one** ``<conditionset>`` needs to be true to trigger the rule (logical OR). An empty condition set is considered to be true, as in, the rule will be always-on. - **All** conditions in a ``<conditionset>`` must be true to make the ``<conditionset>`` true. (logical AND) - For backwards compatibility a ``<rule>`` can contain ``<condition>`` elements outside of a conditionset. These are then understood to be part of a single, implied, ``<conditionset>``. Note: these conditions should be written wrapped in a conditionset. - A rule element needs to contain one or more ``<sub>`` elements in order to be compiled to a variable font. @@ -405,7 +475,7 @@ glyphname pairs: the glyphs that need to be substituted. For a rule to be trigge -------------------------- - Child element of ``<rule>`` -- Contains one or more ``<condition>`` elements. +- Contains zero or more ``<condition>`` elements. ``<condition>`` element @@ -504,7 +574,7 @@ The ``<sources>`` element contains one or more ``<source>`` elements. While this could be extracted from the font data itself, it can be more efficient to add it here. - ``stylename``: optional, string. The style name of the source font. -- ``name``: required, string. A unique name that can be used to +- ``name``: optional, string. A unique name that can be used to identify this font if it needs to be referenced elsewhere. - ``filename``: required, string. A path to the source file, relative to the root path of this document. The path can be at the same level @@ -535,13 +605,13 @@ element with an ``xml:lang`` attribute: Defines the coordinates of this source in the design space. -.. seealso:: `Full documentation of the <location> element <location>`__ +.. seealso:: :ref:`Full documentation of the \<location\> element <location>` ``<dimension>`` element (source) ................................ -.. seealso:: `Full documentation of the <dimension> element <dimension>`__ +.. seealso:: :ref:`Full documentation of the \<dimension\> element <dimension>` ``<lib>`` element (source) @@ -797,7 +867,7 @@ The ``<instances>`` element contains one or more ``<instance>`` elements. - Defines a single font that can be calculated with the designspace. - Child element of ``<instances>`` -- For use in Varlib the instance element really only needs the names +- For use in varLib the instance element really only needs the names and the location. The ``<glyphs>`` element is not required. - MutatorMath uses the ``<glyphs>`` element to describe how certain glyphs need different masters, mainly to describe the effects of @@ -822,6 +892,11 @@ The ``<instances>`` element contains one or more ``<instance>`` elements. with ``styleMapFamilyName`` - ``stylemapstylename``: string. Optional for MutatorMath. Corresponds with ``styleMapStyleName`` +- ``location``: string. Optional. Describes the location of this instance, + taking it from the root level ``<labels>`` (STAT format 4) element with the + same name as the string. + + .. versionadded:: 5.0 ``<location>`` element (instance) @@ -829,13 +904,13 @@ The ``<instances>`` element contains one or more ``<instance>`` elements. Defines the coordinates of this instance in the design space. -.. seealso:: `Full documentation of the <location> element <location>`__ +.. seealso:: :ref:`Full documentation of the \<location\> element <location>` ``<dimension>`` element (instance) .................................. -.. seealso:: `Full documentation of the <dimension> element <dimension>`__ +.. seealso:: :ref:`Full documentation of the \<dimension\> element <dimension>` ``<lib>`` element (instance) @@ -872,7 +947,7 @@ with an ``xml:lang`` attribute: <stylemapfamilyname xml:lang="ja">モンセラート SemiBold</stylemapfamilyname> -Example for varlib +Example for varLib ------------------ .. code:: xml @@ -891,6 +966,30 @@ Example for varlib </instance> +Here is an example using STAT format 4 labels to define the location of the +instance directly. + +.. code:: xml + + <?xml version='1.0' encoding='utf-8'?> + <designspace format="5.0"> + <!-- ... --> + <labels> + <!-- define STAT format 4 labels here --> + <!-- New in version 5.0 --> + <label name="Extra Light"> + <location> + <dimension name="weight" uservalue="123" /> + </location> + </label> + </labels> + <!-- ... --> + <instances> + <instance filename="instances/labelled.ufo" location="Extra Light" /> + </instances> + </designspace> + + ``<glyphs>`` element (instance) ------------------------------- @@ -998,6 +1097,8 @@ Example for MutatorMath The ``<lib>`` element contains arbitrary data. - Child element of ``<designspace>``, ``<variable-font>`` and ``<instance>`` +- If present, content must be an XML Property List (plist). + <https://en.wikipedia.org/wiki/Property_list>__ - Contains arbitrary data about the whole document or about a specific variable font or instance. - Items in the dict need to use **reverse domain name notation** diff --git a/Doc/source/developer.rst b/Doc/source/developer.rst index dc4d425c..e480706a 100644 --- a/Doc/source/developer.rst +++ b/Doc/source/developer.rst @@ -101,13 +101,13 @@ Paul Wise. License ------- -`MIT license <https://github.com/fonttools/fonttools/blob/master/LICENSE>`_. See the full text of the license for details. +`MIT license <https://github.com/fonttools/fonttools/blob/main/LICENSE>`_. See the full text of the license for details. .. |Travis Build Status| image:: https://travis-ci.org/fonttools/fonttools.svg :target: https://travis-ci.org/fonttools/fonttools .. |Appveyor Build status| image:: https://ci.appveyor.com/api/projects/status/0f7fmee9as744sl7/branch/master?svg=true :target: https://ci.appveyor.com/project/fonttools/fonttools/branch/master -.. |Coverage Status| image:: https://codecov.io/gh/fonttools/fonttools/branch/master/graph/badge.svg +.. |Coverage Status| image:: https://codecov.io/gh/fonttools/fonttools/branch/main/graph/badge.svg :target: https://codecov.io/gh/fonttools/fonttools .. |PyPI| image:: https://img.shields.io/pypi/v/fonttools.svg :target: https://pypi.org/project/FontTools diff --git a/Doc/source/index.rst b/Doc/source/index.rst index 571ef8dd..e9b1dd8e 100644 --- a/Doc/source/index.rst +++ b/Doc/source/index.rst @@ -13,14 +13,14 @@ About fontTools is a family of libraries and utilities for manipulating fonts in Python. -The project has an `MIT open-source license <https://github.com/fonttools/fonttools/blob/master/LICENSE>`_. Among other things this means you can use it free of charge. +The project has an `MIT open-source license <https://github.com/fonttools/fonttools/blob/main/LICENSE>`_. Among other things this means you can use it free of charge. Installation ------------ .. note:: - fontTools requires `Python <http://www.python.org/download/>`_ 3.6 or later. + fontTools requires `Python <http://www.python.org/download/>`_ 3.8 or later. The package is listed in the Python Package Index (PyPI), so you can install it with `pip <https://pip.pypa.io/>`_:: @@ -56,6 +56,7 @@ This last utility takes a subcommand, which could be one of: - ``varLib.models``: Normalize locations on a given designspace - ``varLib.mutator``: Instantiate a variation font - ``varLib.varStore``: Optimize a font's GDEF variation store +- ``voltLib.voltToFea``: Convert MS VOLT to AFDKO feature files. Libraries --------- @@ -88,7 +89,7 @@ libraries in the fontTools suite: - :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 <https://github.com/fonttools/fonttools/blob/master/Snippets/>`_ of the fontTools repository. +A selection of sample Python programs using these libaries can be found in the `Snippets directory <https://github.com/fonttools/fonttools/blob/main/Snippets/>`_ of the fontTools repository. Optional Dependencies --------------------- @@ -107,7 +108,7 @@ Information for developers can be found :doc:`here <./developer>`. License ------- -`MIT license <https://github.com/fonttools/fonttools/blob/master/LICENSE>`_. See the full text of the license for details. +`MIT license <https://github.com/fonttools/fonttools/blob/main/LICENSE>`_. See the full text of the license for details. Table of Contents @@ -141,14 +142,14 @@ Table of Contents unicode unicodedata/index varLib/index - voltLib + voltLib/index .. |Travis Build Status| image:: https://travis-ci.org/fonttools/fonttools.svg :target: https://travis-ci.org/fonttools/fonttools .. |Appveyor Build status| image:: https://ci.appveyor.com/api/projects/status/0f7fmee9as744sl7/branch/master?svg=true :target: https://ci.appveyor.com/project/fonttools/fonttools/branch/master -.. |Coverage Status| image:: https://codecov.io/gh/fonttools/fonttools/branch/master/graph/badge.svg +.. |Coverage Status| image:: https://codecov.io/gh/fonttools/fonttools/branch/main/graph/badge.svg :target: https://codecov.io/gh/fonttools/fonttools .. |PyPI| image:: https://img.shields.io/pypi/v/fonttools.svg :target: https://pypi.org/project/FontTools diff --git a/Doc/source/voltLib.rst b/Doc/source/voltLib/index.rst index be9e8024..00d067a2 100644 --- a/Doc/source/voltLib.rst +++ b/Doc/source/voltLib/index.rst @@ -1,6 +1,11 @@ -####### -voltLib -####### +#################################### +voltLib: Read/write MS VOLT projects +#################################### + +.. toctree:: + :maxdepth: 2 + + voltToFea .. automodule:: fontTools.voltLib diff --git a/Doc/source/voltLib/voltToFea.rst b/Doc/source/voltLib/voltToFea.rst new file mode 100644 index 00000000..178dd68d --- /dev/null +++ b/Doc/source/voltLib/voltToFea.rst @@ -0,0 +1,8 @@ +################################################# +voltToFea: Convert MS VOLT to AFDKO feature files +################################################# + +.. automodule:: fontTools.voltLib.voltToFea + :inherited-members: + :members: + :undoc-members: |