shadowfacts/fonttools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[designspaceLib] Freshen the documentation of designspaceLib

Browse Source
This commit is contained in:
Jany Belluz 2018-02-13 17:55:27 +00:00
parent 4c91f51aed
commit a0a2dcb87f
2 changed files with 88 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
Doc/source/designspaceLib/readme.rst
View File

@ -1,5 +1,6 @@
DesignSpaceDocument #################################
=================== DesignSpaceDocument Specification
#################################
An object to read, write and edit interpolation systems for typefaces. An object to read, write and edit interpolation systems for typefaces.
@ -38,13 +39,14 @@ different objects, as long as they have the same attributes.
doc.sources doc.sources
doc.instances doc.instances
**********
Validation Validation
========== **********
Some validation is done when reading. Some validation is done when reading.
Axes Axes
~~~~ ====
- If the ``axes`` element is available in the document then all - If the ``axes`` element is available in the document then all
locations will check their dimensions against the defined axes. If a locations will check their dimensions against the defined axes. If a
@ -56,7 +58,7 @@ Axes
there. there.
Default font Default font
~~~~~~~~~~~~ ============
- The source with the ``copyInfo`` flag indicates this is the default - The source with the ``copyInfo`` flag indicates this is the default
font. font.
@ -68,16 +70,18 @@ Default font
the document this flag will be set. the document this flag will be set.
- Use ``doc.checkDefault()`` to set the default font. - Use ``doc.checkDefault()`` to set the default font.
************
Localisation Localisation
============ ************
Some of the descriptors support localised names. The names are stored in Some of the descriptors support localised names. The names are stored in
dictionaries using the language code as key. That means that there are dictionaries using the language code as key. That means that there are
now two places to store names: the old attribute and the new localised now two places to store names: the old attribute and the new localised
dictionary, ``obj.stylename`` and ``obj.localisedStyleName['en']``. dictionary, ``obj.stylename`` and ``obj.localisedStyleName['en']``.
*****
Rules Rules
===== *****
**The ``rule`` element is experimental.** Some ideas behind how rules **The ``rule`` element is experimental.** Some ideas behind how rules
could work in designspaces come from Superpolator. Such rules can maybe could work in designspaces come from Superpolator. Such rules can maybe
@ -87,7 +91,7 @@ has a name, and it has a number of conditions. The rule also contains a
list of glyphname pairs: the glyphs that need to be substituted. list of glyphname pairs: the glyphs that need to be substituted.
Variable font instances Variable font instances
~~~~~~~~~~~~~~~~~~~~~~~ =======================
- In an variable font the substitution happens at run time: there are - In an variable font the substitution happens at run time: there are
no changes in the font, only in the sequence of glyphnames that is no changes in the font, only in the sequence of glyphnames that is
@ -96,7 +100,7 @@ Variable font instances
be built. be built.
UFO instances UFO instances
~~~~~~~~~~~~~ =============
- When making instances as UFOs however, we need to swap the glyphs so - When making instances as UFOs however, we need to swap the glyphs so
that the original shape is still available. For instance, if a rule that the original shape is still available. For instance, if a rule
@ -110,11 +114,17 @@ UFO instances
- The swap function also needs to take care of swapping the names in - The swap function also needs to take care of swapping the names in
kerning data. kerning data.
**********
Python API
**********
.. _source-descriptor-object:
SourceDescriptor object SourceDescriptor object
----------------------- =======================
Attributes Attributes
~~~~~~~~~~ ----------
- ``filename``: string. A relative path to the source file, **as it is - ``filename``: string. A relative path to the source file, **as it is
in the document**. MutatorMath + Varlib. in the document**. MutatorMath + Varlib.
@ -164,13 +174,15 @@ Attributes
s1.mutedGlyphNames.append("Z") s1.mutedGlyphNames.append("Z")
doc.addSource(s1) doc.addSource(s1)
.. _instance-descriptor-object:
InstanceDescriptor object InstanceDescriptor object
------------------------- =========================
.. attributes-1: .. attributes-1:
Attributes Attributes
~~~~~~~~~~ ----------
- ``filename``: string. Relative path to the instance file, **as it is - ``filename``: string. Relative path to the instance file, **as it is
in the document**. The file may or may not exist. MutatorMath. in the document**. The file may or may not exist. MutatorMath.
@ -211,7 +223,7 @@ Attributes
font.info calculated. font.info calculated.
Methods Methods
~~~~~~~ -------
These methods give easier access to the localised names. These methods give easier access to the localised names.
@ -225,7 +237,7 @@ These methods give easier access to the localised names.
- ``getStyleMapFamilyName(languageCode="en")`` - ``getStyleMapFamilyName(languageCode="en")``
Example Example
~~~~~~~ -------
.. code:: python .. code:: python
@ -248,8 +260,10 @@ Example
i2.glyphs['arrow2'] = dict(mute=False) i2.glyphs['arrow2'] = dict(mute=False)
doc.addInstance(i2) doc.addInstance(i2)
.. _axis-descriptor-object:
AxisDescriptor object AxisDescriptor object
--------------------- =====================
- ``tag``: string. Four letter tag for this axis. Some might be - ``tag``: string. Four letter tag for this axis. Some might be
registered at the `OpenType registered at the `OpenType
@ -285,7 +299,7 @@ AxisDescriptor object
a1.map = [(1.0, 10.0), (400.0, 66.0), (1000.0, 990.0)] a1.map = [(1.0, 10.0), (400.0, 66.0), (1000.0, 990.0)]
RuleDescriptor object RuleDescriptor object
--------------------- =====================
- ``name``: string. Unique name for this rule. Will be used to - ``name``: string. Unique name for this rule. Will be used to
reference this rule data. reference this rule data.
@ -300,6 +314,8 @@ RuleDescriptor object
r1.conditions.append(dict(name="weight", minimum=-10, maximum=10)) r1.conditions.append(dict(name="weight", minimum=-10, maximum=10))
r1.conditions.append(dict(name="width", minimum=-10, maximum=10)) r1.conditions.append(dict(name="width", minimum=-10, maximum=10))
.. _subclassing-descriptors:
Subclassing descriptors Subclassing descriptors
======================= =======================
@ -324,8 +340,9 @@ descriptor does not need to be a subclass.
myDoc = DesignSpaceDocument(KeyedDocReader, KeyedDocWriter) myDoc = DesignSpaceDocument(KeyedDocReader, KeyedDocWriter)
**********************
Document xml structure Document xml structure
====================== **********************
- The ``axes`` element contains one or more ``axis`` elements. - The ``axes`` element contains one or more ``axis`` elements.
- The ``sources`` element contains one or more ``source`` elements. - The ``sources`` element contains one or more ``source`` elements.
@ -360,7 +377,7 @@ Document xml structure
.. attributes-2: .. attributes-2:
Attributes Attributes
~~~~~~~~~~ ----------
- ``name``: required, string. Name of the axis that is used in the - ``name``: required, string. Name of the axis that is used in the
location elements. location elements.
@ -389,20 +406,20 @@ Attributes
.. attributes-3: .. attributes-3:
Attributes Attributes
~~~~~~~~~~ ----------
- ``xml:lang``: required, string. `XML language - ``xml:lang``: required, string. `XML language
definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__ definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__
Value Value
~~~~~ -----
- The natural language name of this axis. - The natural language name of this axis.
.. example-1: .. example-1:
Example Example
~~~~~~~ -------
.. code:: xml .. code:: xml
@ -422,7 +439,7 @@ Example
.. example-2: .. example-2:
Example Example
~~~~~~~ -------
.. code:: xml .. code:: xml
@ -431,7 +448,7 @@ Example
<map input="1000.0" output="990.0" /> <map input="1000.0" output="990.0" />
Example of all axis elements together: Example of all axis elements together:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------
.. code:: xml .. code:: xml
@ -466,7 +483,7 @@ Example of all axis elements together:
.. attributes-4: .. attributes-4:
Attributes Attributes
~~~~~~~~~~ ----------
- ``name``: required, string. Name of the axis. - ``name``: required, string. Name of the axis.
- ``xvalue``: required, number. The value on this axis. - ``xvalue``: required, number. The value on this axis.
@ -476,7 +493,7 @@ Attributes
.. example-3: .. example-3:
Example Example
~~~~~~~ -------
.. code:: xml .. code:: xml
@ -496,7 +513,7 @@ Example
.. attributes-5: .. attributes-5:
Attributes Attributes
~~~~~~~~~~ ----------
- ``familyname``: optional, string. The family name of the source font. - ``familyname``: optional, string. The family name of the source font.
While this could be extracted from the font data itself, it can be While this could be extracted from the font data itself, it can be
@ -556,7 +573,7 @@ Attributes
.. attributes-6: .. attributes-6:
Attributes Attributes
~~~~~~~~~~ ----------
- ``mute``: optional attribute, number 1 or 0. Indicate if this glyph - ``mute``: optional attribute, number 1 or 0. Indicate if this glyph
should be ignored as a master. should be ignored as a master.
@ -574,7 +591,7 @@ Attributes
.. attributes-7: .. attributes-7:
Attributes Attributes
~~~~~~~~~~ ----------
- ``mute``: required attribute, number 1 or 0. Indicate if the kerning - ``mute``: required attribute, number 1 or 0. Indicate if the kerning
data from this source is to be excluded from the calculation. data from this source is to be excluded from the calculation.
@ -585,7 +602,7 @@ Attributes
.. example-4: .. example-4:
Example Example
~~~~~~~ -------
.. code:: xml .. code:: xml
@ -617,7 +634,7 @@ Example
.. attributes-8: .. attributes-8:
Attributes Attributes
~~~~~~~~~~ ----------
- ``familyname``: required, string. The family name of the instance - ``familyname``: required, string. The family name of the instance
font. Corresponds with ``font.info.familyName`` font. Corresponds with ``font.info.familyName``
@ -636,7 +653,7 @@ Attributes
with ``styleMapStyleName`` with ``styleMapStyleName``
Example for varlib Example for varlib
~~~~~~~~~~~~~~~~~~ ------------------
.. code:: xml .. code:: xml
@ -669,7 +686,7 @@ Example for varlib
.. attributes-9: .. attributes-9:
Attributes Attributes
~~~~~~~~~~ ----------
- ``name``: string. The name of the glyph. - ``name``: string. The name of the glyph.
- ``unicode``: string. Unicode values for this glyph, in hexadecimal. - ``unicode``: string. Unicode values for this glyph, in hexadecimal.
@ -713,7 +730,7 @@ definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__
.. example-5: .. example-5:
Example Example
~~~~~~~ -------
.. code:: xml .. code:: xml
@ -728,7 +745,7 @@ Example
.. attributes-10: .. attributes-10:
Attributes Attributes
~~~~~~~~~~ ----------
- ``glyphname``: the name of the alternate master glyph. - ``glyphname``: the name of the alternate master glyph.
- ``source``: the identifier name of the source this master glyph needs - ``source``: the identifier name of the source this master glyph needs
@ -737,7 +754,7 @@ Attributes
.. example-6: .. example-6:
Example Example
~~~~~~~ -------
.. code:: xml .. code:: xml
@ -790,7 +807,7 @@ Example
.. attributes-11: .. attributes-11:
Attributes Attributes
~~~~~~~~~~ ----------
- ``name``: required, string. A unique name that can be used to - ``name``: required, string. A unique name that can be used to
identify this rule if it needs to be referenced elsewhere. identify this rule if it needs to be referenced elsewhere.
@ -809,7 +826,7 @@ Attributes
.. attributes-12: .. attributes-12:
Attributes Attributes
~~~~~~~~~~ ----------
- ``name``: string, required. Must match one of the defined ``axis`` - ``name``: string, required. Must match one of the defined ``axis``
name attributes. name attributes.
@ -829,7 +846,7 @@ Attributes
.. attributes-13: .. attributes-13:
Attributes Attributes
~~~~~~~~~~ ----------
- ``name``: string, required. The name of the glyph this rule looks - ``name``: string, required. The name of the glyph this rule looks
for. for.
@ -839,7 +856,7 @@ Attributes
.. example-7: .. example-7:
Example Example
~~~~~~~ -------
.. code:: xml .. code:: xml

59
Doc/source/designspaceLib/scripting.rst
View File

@ -1,25 +1,29 @@
#######################
Scripting a designspace Scripting a designspace
======================= #######################
It can be useful to build a designspace with a script rather than It can be useful to build a designspace with a script rather than
construct one with an interface like construct one with an interface like
`Superpolator <http://superpolator.com>`__ or `Superpolator <http://superpolator.com>`__ or
`DesignSpaceEditor <https://github.com/LettError/designSpaceRoboFontExtension>`__. `DesignSpaceEditor <https://github.com/LettError/designSpaceRoboFontExtension>`__.
The
`designSpaceDocument <https://github.com/LettError/designSpaceDocument>`__
offers a some tools for building designspaces in Python. This document
shows an example.
So, suppose you installed the `fontTools.designspaceLib` offers a some tools for building designspaces in
`designSpaceDocument <https://github.com/LettError/designSpaceDocument>`__ Python. This document shows an example.
package through your favorite ``git`` client.
********************************
Filling-in a DesignSpaceDocument
********************************
So, suppose you installed the `fontTools` package through your favorite
``git`` client.
The ``DesignSpaceDocument`` object represents the document, whether it The ``DesignSpaceDocument`` object represents the document, whether it
already exists or not. Make a new one: already exists or not. Make a new one:
.. code:: python .. code:: python
from designSpaceDocument import DesignSpaceDocument, AxisDescriptor, SourceDescriptor, InstanceDescriptor from fontTools.designspaceLib import (DesignSpaceDocument, AxisDescriptor,
SourceDescriptor, InstanceDescriptor)
doc = DesignSpaceDocument() doc = DesignSpaceDocument()
We want to create definitions for axes, sources and instances. That We want to create definitions for axes, sources and instances. That
@ -28,17 +32,13 @@ object** uses objects to describe the axes, sources and instances. These
are relatively simple objects, think of these as collections of are relatively simple objects, think of these as collections of
attributes. attributes.
- `Attributes of the Source - Attributes of the :ref:`source-descriptor-object`
descriptor <https://github.com/LettError/designSpaceDocument#source-descriptor-object-attributes>`__ - Attributes of the :ref:`instance-descriptor-object`
- `Attributes of the Instance - Attributes of the :ref:`axis-descriptor-object`
descriptor <https://github.com/LettError/designSpaceDocument#instance-descriptor-object>`__ - Read about :ref:`subclassing-descriptors`
- `Attributes of the Axis
descriptor <https://github.com/LettError/designSpaceDocument#axis-descriptor-object>`__
- Read about `subclassing
descriptors <https://github.com/LettError/designSpaceDocument#subclassing-descriptors>`__
Make an axis object Make an axis object
------------------- ===================
Make a descriptor object and add it to the document. Make a descriptor object and add it to the document.
@ -61,7 +61,7 @@ Make a descriptor object and add it to the document.
Tags <https://www.microsoft.com/typography/otspec/fvar.htm#VAT>`__ Tags <https://www.microsoft.com/typography/otspec/fvar.htm#VAT>`__
Option: add label names Option: add label names
~~~~~~~~~~~~~~~~~~~~~~~ -----------------------
The **labelnames** attribute is intended to store localisable, human The **labelnames** attribute is intended to store localisable, human
readable names for this axis if this is not an axis that is registered readable names for this axis if this is not an axis that is registered
@ -78,7 +78,7 @@ authoring software. This, at least, is the place to record it.
a1.labelNames['en'] = u"Wéíght" a1.labelNames['en'] = u"Wéíght"
Option: add a map Option: add a map
~~~~~~~~~~~~~~~~~ -----------------
The **map** attribute is a list of (input, output) mapping values The **map** attribute is a list of (input, output) mapping values
intended for `axis variations table of intended for `axis variations table of
@ -89,7 +89,7 @@ OpenType <https://www.microsoft.com/typography/otspec/avar.htm>`__.
a1.map = [(0.0, 10.0), (401.0, 66.0), (1000.0, 990.0)] a1.map = [(0.0, 10.0), (401.0, 66.0), (1000.0, 990.0)]
Make a source object Make a source object
-------------------- ====================
A **source** is an object that points to a UFO file. It provides the A **source** is an object that points to a UFO file. It provides the
outline geometry, kerning and font.info that we want to work with. outline geometry, kerning and font.info that we want to work with.
@ -123,7 +123,7 @@ So go ahead and add another master:
doc.addSource(s1) doc.addSource(s1)
Option: exclude glyphs Option: exclude glyphs
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
By default all glyphs in a source will be processed. If you want to By default all glyphs in a source will be processed. If you want to
exclude certain glyphs, add their names to the ``mutedGlyphNames`` list. exclude certain glyphs, add their names to the ``mutedGlyphNames`` list.
@ -133,7 +133,7 @@ exclude certain glyphs, add their names to the ``mutedGlyphNames`` list.
s1.mutedGlyphNames = ["A.test", "A.old"] s1.mutedGlyphNames = ["A.test", "A.old"]
Make an instance object Make an instance object
----------------------- =======================
An **instance** is description of a UFO that you want to generate with An **instance** is description of a UFO that you want to generate with
the designspace. For an instance you can define more things. If you want the designspace. For an instance you can define more things. If you want
@ -161,7 +161,7 @@ and so on. You can also set a path where to generate the instance.
- Instances for variable fonts become **named instances**. - Instances for variable fonts become **named instances**.
Option: add more names Option: add more names
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
If you want you can add a PostScript font name, a stylemap familyName If you want you can add a PostScript font name, a stylemap familyName
and a stylemap styleName. and a stylemap styleName.
@ -173,7 +173,7 @@ and a stylemap styleName.
i0.styleMapStyleName = "regular" i0.styleMapStyleName = "regular"
Option: add glyph specific masters Option: add glyph specific masters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------
This bit is not supported by OpenType variable fonts, but it is needed This bit is not supported by OpenType variable fonts, but it is needed
for some designspaces intended for generating instances with for some designspaces intended for generating instances with
@ -207,16 +207,18 @@ this into something clever.
# With all of that set up, store it in the instance. # With all of that set up, store it in the instance.
i4.glyphs['dollar'] = glyphData i4.glyphs['dollar'] = glyphData
******
Saving Saving
====== ******
.. code:: python .. code:: python
path = "myprototype.designspace" path = "myprototype.designspace"
doc.write(path) doc.write(path)
************************
Reading old designspaces Reading old designspaces
======================== ************************
Old designspace files might not contain ``axes`` definitions. This is Old designspace files might not contain ``axes`` definitions. This is
how you reconstruct the axes from the extremes of the source locations how you reconstruct the axes from the extremes of the source locations
@ -231,8 +233,9 @@ This is how you check the default font.
doc.checkDefault() doc.checkDefault()
***********
Generating? Generating?
=========== ***********
You can generate the UFO's with MutatorMath: You can generate the UFO's with MutatorMath: