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

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

@ -1,25 +1,29 @@
#######################
Scripting a designspace
=======================
#######################
It can be useful to build a designspace with a script rather than
construct one with an interface like
`Superpolator <http://superpolator.com>`__ or
`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
`designSpaceDocument <https://github.com/LettError/designSpaceDocument>`__
package through your favorite ``git`` client.
`fontTools.designspaceLib` offers a some tools for building designspaces in
Python. This document shows an example.
********************************
Filling-in a DesignSpaceDocument
********************************
So, suppose you installed the `fontTools` package through your favorite
``git`` client.
The ``DesignSpaceDocument`` object represents the document, whether it
already exists or not. Make a new one:
.. code:: python
from designSpaceDocument import DesignSpaceDocument, AxisDescriptor, SourceDescriptor, InstanceDescriptor
from fontTools.designspaceLib import (DesignSpaceDocument, AxisDescriptor,
SourceDescriptor, InstanceDescriptor)
doc = DesignSpaceDocument()
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
attributes.
- `Attributes of the Source
descriptor <https://github.com/LettError/designSpaceDocument#source-descriptor-object-attributes>`__
- `Attributes of the Instance
descriptor <https://github.com/LettError/designSpaceDocument#instance-descriptor-object>`__
- `Attributes of the Axis
descriptor <https://github.com/LettError/designSpaceDocument#axis-descriptor-object>`__
- Read about `subclassing
descriptors <https://github.com/LettError/designSpaceDocument#subclassing-descriptors>`__
- Attributes of the :ref:`source-descriptor-object`
- Attributes of the :ref:`instance-descriptor-object`
- Attributes of the :ref:`axis-descriptor-object`
- Read about :ref:`subclassing-descriptors`
Make an axis object
-------------------
===================
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>`__
Option: add label names
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
The **labelnames** attribute is intended to store localisable, human
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"
Option: add a map
~~~~~~~~~~~~~~~~~
-----------------
The **map** attribute is a list of (input, output) mapping values
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)]
Make a source object
--------------------
====================
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.
@ -123,7 +123,7 @@ So go ahead and add another master:
doc.addSource(s1)
Option: exclude glyphs
~~~~~~~~~~~~~~~~~~~~~~
----------------------
By default all glyphs in a source will be processed. If you want to
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"]
Make an instance object
-----------------------
=======================
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
@ -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**.
Option: add more names
~~~~~~~~~~~~~~~~~~~~~~
----------------------
If you want you can add a PostScript font name, a stylemap familyName
and a stylemap styleName.
@ -173,7 +173,7 @@ and a stylemap styleName.
i0.styleMapStyleName = "regular"
Option: add glyph specific masters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------
This bit is not supported by OpenType variable fonts, but it is needed
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.
i4.glyphs['dollar'] = glyphData
******
Saving
======
******
.. code:: python
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
@ -231,8 +233,9 @@ This is how you check the default font.
doc.checkDefault()
***********
Generating?
===========
***********
You can generate the UFO's with MutatorMath: