From a0a2dcb87fc3c9f14bd43e0ad74aa8e7bc2ce351 Mon Sep 17 00:00:00 2001 From: Jany Belluz Date: Tue, 13 Feb 2018 17:55:27 +0000 Subject: [PATCH] [designspaceLib] Freshen the documentation of designspaceLib --- Doc/source/designspaceLib/readme.rst | 97 +++++++++++++++---------- Doc/source/designspaceLib/scripting.rst | 59 ++++++++------- 2 files changed, 88 insertions(+), 68 deletions(-) diff --git a/Doc/source/designspaceLib/readme.rst b/Doc/source/designspaceLib/readme.rst index 02b4f79ca..5c32bb898 100644 --- a/Doc/source/designspaceLib/readme.rst +++ b/Doc/source/designspaceLib/readme.rst @@ -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 `__ 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 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 `__ .. 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 diff --git a/Doc/source/designspaceLib/scripting.rst b/Doc/source/designspaceLib/scripting.rst index 614fa9107..214d98d00 100644 --- a/Doc/source/designspaceLib/scripting.rst +++ b/Doc/source/designspaceLib/scripting.rst @@ -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 `__ or `DesignSpaceEditor `__. -The -`designSpaceDocument `__ -offers a some tools for building designspaces in Python. This document -shows an example. -So, suppose you installed the -`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 `__ -- `Attributes of the Instance - descriptor `__ -- `Attributes of the Axis - descriptor `__ -- Read about `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 `__ 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 `__. 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: