1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
#######################################################
designspaceLib: Read, write, and edit designspace files
#######################################################
Implements support for reading and manipulating ``designspace`` files.
Allows the users to define axes, rules, sources, variable fonts and instances,
and their STAT information.
.. toctree::
:maxdepth: 1
python
xml
scripting
Notes
=====
Paths and filenames
-------------------
A designspace file needs to store many references to UFO files.
- designspace files can be part of versioning systems and appear on
different computers. This means it is not possible to store absolute
paths.
- So, all paths are relative to the designspace document path.
- Using relative paths allows designspace files and UFO files to be
**near** each other, and that they can be **found** without enforcing
one particular structure.
- The **filename** attribute in the ``SourceDescriptor`` and
``InstanceDescriptor`` classes stores the preferred relative path.
- The **path** attribute in these objects stores the absolute path. It
is calculated from the document path and the relative path in the
filename attribute when the object is created.
- Only the **filename** attribute is written to file.
- Both **filename** and **path** must use forward slashes (``/``) as
path separators, even on Windows.
Right before we save we need to identify and respond to the following
situations:
In each descriptor, we have to do the right thing for the filename
attribute. Before writing to file, the ``documentObject.updatePaths()``
method prepares the paths as follows:
**Case 1**
::
descriptor.filename == None
descriptor.path == None
**Action**
- write as is, descriptors will not have a filename attr. Useless, but
no reason to interfere.
**Case 2**
::
descriptor.filename == "../something"
descriptor.path == None
**Action**
- write as is. The filename attr should not be touched.
**Case 3**
::
descriptor.filename == None
descriptor.path == "~/absolute/path/there"
**Action**
- calculate the relative path for filename. We're not overwriting some
other value for filename, it should be fine.
**Case 4**
::
descriptor.filename == '../somewhere'
descriptor.path == "~/absolute/path/there"
**Action**
- There is a conflict between the given filename, and the path. The
difference could have happened for any number of reasons. Assuming
the values were not in conflict when the object was created, either
could have changed. We can't guess.
- Assume the path attribute is more up to date. Calculate a new value
for filename based on the path and the document path.
Recommendation for editors
--------------------------
- If you want to explicitly set the **filename** attribute, leave the
path attribute empty.
- If you want to explicitly set the **path** attribute, leave the
filename attribute empty. It will be recalculated.
- Use ``documentObject.updateFilenameFromPath()`` to explicitly set the
**filename** attributes for all instance and source descriptors.
Common Lib Key Registry
=======================
public.skipExportGlyphs
-----------------------
This lib key works the same as the UFO lib key with the same name. The
difference is that applications using a Designspace as the corner stone of the
font compilation process should use the lib key in that Designspace instead of
any of the UFOs. If the lib key is empty or not present in the Designspace, all
glyphs should be exported, regardless of what the same lib key in any of the
UFOs says.
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.
- not all values are be required by all implementations.
Varlib vs. MutatorMath
----------------------
There are some differences between the way MutatorMath and fontTools.varlib handle designspaces.
- 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
MutatorMath.
- The goals of Varlib and MutatorMath are different, so not all
attributes are always needed.
Rules and generating static UFO instances
-----------------------------------------
When making instances as UFOs from a designspace with rules, it can
be useful to evaluate the rules so that the characterset of the UFO
reflects, as much as possible, the state of a variable font when seen
at the same location. This can be done by some swapping and renaming of
glyphs.
While useful for proofing or development work, it should be noted that
swapping and renaming leaves the UFOs with glyphnames that are no longer
descriptive. For instance, after a swap ``dollar.bar`` could contain a shape
without a bar. Also, when the swapped glyphs are part of other GSUB variations
it can become complex very quickly. So proceed with caution.
- Assuming ``rulesProcessingLast = True``:
- We need to swap the glyphs so that the original shape is still available.
For instance, if a rule swaps ``a`` for ``a.alt``, a glyph
that references ``a`` in a component would then show the new ``a.alt``.
- But that can lead to unexpected results, the two glyphs may have different
widths or height. So, glyphs that are not specifically referenced in a rule
**should not change appearance**. That means that the implementation that swaps
``a`` and ``a.alt`` also swap all components that reference these
glyphs in order to preserve their appearance.
- The swap function also needs to take care of swapping the names in
kerning data and any GPOS code.
Version history
===============
Version 5.0
-----------
The format was extended to describe the entire design space of a reasonably
regular font family in one file, with global data about the family to reduce
repetition in sub-sections. "Reasonably regular" means that the sources and
instances across the previously multiple Designspace files are positioned on a
grid and derive their metadata (like style name) in a way that's compatible with
the STAT model, based on their axis positions. Axis mappings must be the same
across the entire space.
1. Each axis can have labels attached to stops within the axis range, analogous to the
`OpenType STAT <https://docs.microsoft.com/en-us/typography/opentype/spec/stat>`_
table. Free-standing labels for locations are also allowed. The data is intended
to be compiled into a ``STAT`` table.
2. The axes can be discrete, to say that they do not interpolate, like a distinctly
constructed upright and italic variant of a family.
3. The data can be used to derive style and PostScript names for instances.
4. A new ``variable-fonts`` element can subdivide the Designspace into multiple subsets that
mix and match the globally available axes. It is possible for these sub-spaces to have
a different default location from the global default location. It is required if the
Designspace contains a discrete axis and you want to produce a variable font.
What is currently not supported is e.g.
1. A setup where different sources sit at the same logical location in the design space,
think "MyFont Regular" and "MyFont SmallCaps Regular". (this situation could be
encoded by adding a "SmallCaps" discrete axis, if that makes sense).
2. Anisotropic locations for axis labels.
Older versions
--------------
- In some implementations that preceed Variable Fonts, the `copyInfo`
flag in a source indicated the source was to be treated as the default.
This is no longer compatible with the assumption that the default font
is located on the default value of each axis.
- Older implementations did not require axis records to be present in
the designspace file. The axis extremes for instance were generated
from the locations used in the sources. This is no longer possible.
|
