1 ################################# 2 DesignSpaceDocument Specification 3 ################################# 4 5 An object to read, write and edit interpolation systems for typefaces. 6 7 - the format was originally written for MutatorMath. 8 - the format is now also used in fontTools.varlib. 9 - Define sources, axes and instances. 10 - Not all values might be required by all applications. 11 12 A couple of differences between things that use designspaces: 13 14 - Varlib does not support anisotropic interpolations. 15 - MutatorMath and Superpolator will extrapolate over the boundaries of 16 the axes. Varlib can not (at the moment). 17 - Varlib requires much less data to define an instance than 18 MutatorMath. 19 - The goals of Varlib and MutatorMath are different, so not all 20 attributes are always needed. 21 - Need to expand the description of FDK use of designspace files. 22 23 The DesignSpaceDocument object can read and write ``.designspace`` data. 24 It imports the axes, sources and instances to very basic **descriptor** 25 objects that store the data in attributes. Data is added to the document 26 by creating such descriptor objects, filling them with data and then 27 adding them to the document. This makes it easy to integrate this object 28 in different contexts. 29 30 The **DesignSpaceDocument** object can be subclassed to work with 31 different objects, as long as they have the same attributes. 32 33 .. code:: python 34 35 from designSpaceDocument import DesignSpaceDocument 36 doc = DesignSpaceDocument() 37 doc.read("some/path/to/my.designspace") 38 doc.axes 39 doc.sources 40 doc.instances 41 42 ********** 43 Validation 44 ********** 45 46 Some validation is done when reading. 47 48 Axes 49 ==== 50 51 - If the ``axes`` element is available in the document then all 52 locations will check their dimensions against the defined axes. If a 53 location uses an axis that is not defined it will be ignored. 54 - If there are no ``axes`` in the document, locations will accept all 55 axis names, so that we can.. 56 - Use ``doc.checkAxes()`` to reconstruct axes definitions based on the 57 ``source.location`` values. If you save the document the axes will be 58 there. 59 60 Default font 61 ============ 62 63 - The source with the ``copyInfo`` flag indicates this is the default 64 font. 65 - In mutatorMath the default font is selected automatically. A warning 66 is printed if the mutatorMath default selection differs from the one 67 set by ``copyInfo``. But the ``copyInfo`` source will be used. 68 - If no source has a ``copyInfo`` flag, mutatorMath will be used to 69 select one. This source gets its ``copyInfo`` flag set. If you save 70 the document this flag will be set. 71 - Use ``doc.checkDefault()`` to set the default font. 72 73 ************ 74 Localisation 75 ************ 76 77 Some of the descriptors support localised names. The names are stored in 78 dictionaries using the language code as key. That means that there are 79 now two places to store names: the old attribute and the new localised 80 dictionary, ``obj.stylename`` and ``obj.localisedStyleName['en']``. 81 82 ***** 83 Rules 84 ***** 85 86 Rules describe designspace areas in which one glyph should be replaced by another. 87 A rule has a name and a number of conditionsets. The rule also contains a list of 88 glyphname pairs: the glyphs that need to be substituted. For a rule to be triggered 89 **only one** of the conditionsets needs to be true, ``OR``. Within a conditionset 90 **all** conditions need to be true, ``AND``. 91 92 The ``sub`` element contains a pair of glyphnames. The ``name`` attribute is the glyph that should be visible when the rule evaluates to **False**. The ``with`` attribute is the glyph that should be visible when the rule evaluates to **True**. 93 94 UFO instances 95 ============= 96 97 - When making instances as UFOs however, we need to swap the glyphs so 98 that the original shape is still available. For instance, if a rule 99 swaps ``a`` for ``a.alt``, but a glyph that references ``a`` in a 100 component would then show the new ``a.alt``. 101 - But that can lead to unexpected results. So, if there are no rules 102 for ``adieresis`` (assuming it references ``a``) then that glyph 103 **should not change appearance**. That means that when the rule swaps 104 ``a`` and ``a.alt`` it also swaps all components that reference these 105 glyphs so they keep their appearance. 106 - The swap function also needs to take care of swapping the names in 107 kerning data. 108 109 ********** 110 Python API 111 ********** 112 113 SourceDescriptor object 114 ======================= 115 116 Attributes 117 ---------- 118 119 - ``filename``: string. A relative path to the source file, **as it is 120 in the document**. MutatorMath + Varlib. 121 - ``path``: string. Absolute path to the source file, calculated from 122 the document path and the string in the filename attr. MutatorMath + 123 Varlib. 124 - ``layerName``: string. The name of the layer in the source to look for 125 outline data. Default ``None`` which means ``foreground``. 126 - ``font``: Any Python object. Optional. Points to a representation of 127 this source font that is loaded in memory, as a Python object 128 (e.g. a ``defcon.Font`` or a ``fontTools.ttFont.TTFont``). The default 129 document reader will not fill-in this attribute, and the default 130 writer will not use this attribute. It is up to the user of 131 ``designspaceLib`` to either load the resource identified by ``filename`` 132 and store it in this field, or write the contents of this field to the 133 disk and make ``filename`` point to that. 134 - ``name``: string. Optional. Unique identifier name for this source, 135 if there is one or more ``instance.glyph`` elements in the document. 136 MutatorMath. 137 - ``location``: dict. Axis values for this source. MutatorMath + Varlib 138 - ``copyLib``: bool. Indicates if the contents of the font.lib need to 139 be copied to the instances. MutatorMath. 140 - ``copyInfo`` bool. Indicates if the non-interpolating font.info needs 141 to be copied to the instances. Also indicates this source is expected 142 to be the default font. MutatorMath + Varlib 143 - ``copyGroups`` bool. Indicates if the groups need to be copied to the 144 instances. MutatorMath. 145 - ``copyFeatures`` bool. Indicates if the feature text needs to be 146 copied to the instances. MutatorMath. 147 - ``muteKerning``: bool. Indicates if the kerning data from this source 148 needs to be muted (i.e. not be part of the calculations). 149 MutatorMath. 150 - ``muteInfo``: bool. Indicated if the interpolating font.info data for 151 this source needs to be muted. MutatorMath. 152 - ``mutedGlyphNames``: list. Glyphnames that need to be muted in the 153 instances. MutatorMath. 154 - ``familyName``: string. Family name of this source. Though this data 155 can be extracted from the font, it can be efficient to have it right 156 here. Varlib. 157 - ``styleName``: string. Style name of this source. Though this data 158 can be extracted from the font, it can be efficient to have it right 159 here. Varlib. 160 161 .. code:: python 162 163 doc = DesignSpaceDocument() 164 s1 = SourceDescriptor() 165 s1.path = masterPath1 166 s1.name = "master.ufo1" 167 s1.font = defcon.Font("master.ufo1") 168 s1.copyLib = True 169 s1.copyInfo = True 170 s1.copyFeatures = True 171 s1.location = dict(weight=0) 172 s1.familyName = "MasterFamilyName" 173 s1.styleName = "MasterStyleNameOne" 174 s1.mutedGlyphNames.append("A") 175 s1.mutedGlyphNames.append("Z") 176 doc.addSource(s1) 177 178 .. _instance-descriptor-object: 179 180 InstanceDescriptor object 181 ========================= 182 183 .. attributes-1: 184 185 Attributes 186 ---------- 187 188 - ``filename``: string. Relative path to the instance file, **as it is 189 in the document**. The file may or may not exist. MutatorMath. 190 - ``path``: string. Absolute path to the source file, calculated from 191 the document path and the string in the filename attr. The file may 192 or may not exist. MutatorMath. 193 - ``name``: string. Unique identifier name of the instance, used to 194 identify it if it needs to be referenced from elsewhere in the 195 document. 196 - ``location``: dict. Axis values for this source. MutatorMath + 197 Varlib. 198 - ``familyName``: string. Family name of this instance. MutatorMath + 199 Varlib. 200 - ``localisedFamilyName``: dict. A dictionary of localised family name 201 strings, keyed by language code. 202 - ``styleName``: string. Style name of this source. MutatorMath + 203 Varlib. 204 - ``localisedStyleName``: dict. A dictionary of localised stylename 205 strings, keyed by language code. 206 - ``postScriptFontName``: string. Postscript fontname for this 207 instance. MutatorMath. 208 - ``styleMapFamilyName``: string. StyleMap familyname for this 209 instance. MutatorMath. 210 - ``localisedStyleMapFamilyName``: A dictionary of localised style map 211 familyname strings, keyed by language code. 212 - ``localisedStyleMapStyleName``: A dictionary of localised style map 213 stylename strings, keyed by language code. 214 - ``styleMapStyleName``: string. StyleMap stylename for this instance. 215 MutatorMath. 216 - ``glyphs``: dict for special master definitions for glyphs. If glyphs 217 need special masters (to record the results of executed rules for 218 example). MutatorMath. 219 - ``kerning``: bool. Indicates if this instance needs its kerning 220 calculated. MutatorMath. 221 - ``info``: bool. Indicated if this instance needs the interpolating 222 font.info calculated. 223 - ``lib``: dict. Custom data associated with this instance. 224 225 Methods 226 ------- 227 228 These methods give easier access to the localised names. 229 230 - ``setStyleName(styleName, languageCode="en")`` 231 - ``getStyleName(languageCode="en")`` 232 - ``setFamilyName(familyName, languageCode="en")`` 233 - ``getFamilyName(self, languageCode="en")`` 234 - ``setStyleMapStyleName(styleMapStyleName, languageCode="en")`` 235 - ``getStyleMapStyleName(languageCode="en")`` 236 - ``setStyleMapFamilyName(styleMapFamilyName, languageCode="en")`` 237 - ``getStyleMapFamilyName(languageCode="en")`` 238 239 Example 240 ------- 241 242 .. code:: python 243 244 i2 = InstanceDescriptor() 245 i2.path = instancePath2 246 i2.familyName = "InstanceFamilyName" 247 i2.styleName = "InstanceStyleName" 248 i2.name = "instance.ufo2" 249 # anisotropic location 250 i2.location = dict(weight=500, width=(400,300)) 251 i2.postScriptFontName = "InstancePostscriptName" 252 i2.styleMapFamilyName = "InstanceStyleMapFamilyName" 253 i2.styleMapStyleName = "InstanceStyleMapStyleName" 254 glyphMasters = [dict(font="master.ufo1", glyphName="BB", location=dict(width=20,weight=20)), dict(font="master.ufo2", glyphName="CC", location=dict(width=900,weight=900))] 255 glyphData = dict(name="arrow", unicodeValue=1234) 256 glyphData['masters'] = glyphMasters 257 glyphData['note'] = "A note about this glyph" 258 glyphData['instanceLocation'] = dict(width=100, weight=120) 259 i2.glyphs['arrow'] = glyphData 260 i2.glyphs['arrow2'] = dict(mute=False) 261 i2.lib['com.coolDesignspaceApp.specimenText'] = 'Hamburgerwhatever' 262 doc.addInstance(i2) 263 264 .. _axis-descriptor-object: 265 266 AxisDescriptor object 267 ===================== 268 269 - ``tag``: string. Four letter tag for this axis. Some might be 270 registered at the `OpenType 271 specification <https://www.microsoft.com/typography/otspec/fvar.htm#VAT>`__. 272 Privately-defined axis tags must begin with an uppercase letter and 273 use only uppercase letters or digits. 274 - ``name``: string. Name of the axis as it is used in the location 275 dicts. MutatorMath + Varlib. 276 - ``labelNames``: dict. When defining a non-registered axis, it will be 277 necessary to define user-facing readable names for the axis. Keyed by 278 xml:lang code. Values are required to be ``unicode`` strings, even if 279 they only contain ASCII characters. 280 - ``minimum``: number. The minimum value for this axis in user space. 281 MutatorMath + Varlib. 282 - ``maximum``: number. The maximum value for this axis in user space. 283 MutatorMath + Varlib. 284 - ``default``: number. The default value for this axis, i.e. when a new 285 location is created, this is the value this axis will get in user 286 space. MutatorMath + Varlib. 287 - ``map``: list of input / output values that can describe a warp of user space 288 to design space coordinates. If no map values are present, it is assumed user 289 space is the same as design space, as in [(minimum, minimum), (maximum, maximum)]. 290 Varlib. 291 292 .. code:: python 293 294 a1 = AxisDescriptor() 295 a1.minimum = 1 296 a1.maximum = 1000 297 a1.default = 400 298 a1.name = "weight" 299 a1.tag = "wght" 300 a1.labelNames[u'fa-IR'] = u"" 301 a1.labelNames[u'en'] = u"Wght" 302 a1.map = [(1.0, 10.0), (400.0, 66.0), (1000.0, 990.0)] 303 304 RuleDescriptor object 305 ===================== 306 307 - ``name``: string. Unique name for this rule. Can be used to 308 reference this rule data. 309 - ``conditionSets``: a list of conditionsets 310 - Each conditionset is a list of conditions. 311 - Each condition is a dict with ``name``, ``minimum`` and ``maximum`` keys. 312 - ``subs``: list of substitutions 313 - Each substitution is stored as tuples of glyphnames, e.g. ("a", "a.alt"). 314 315 .. code:: python 316 317 r1 = RuleDescriptor() 318 r1.name = "unique.rule.name" 319 r1.conditionsSets.append([dict(name="weight", minimum=-10, maximum=10), dict(...)]) 320 r1.conditionsSets.append([dict(...), dict(...)]) 321 r1.subs.append(("a", "a.alt")) 322 323 .. _subclassing-descriptors: 324 325 Subclassing descriptors 326 ======================= 327 328 The DesignSpaceDocument can take subclassed Reader and Writer objects. 329 This allows you to work with your own descriptors. You could subclass 330 the descriptors. But as long as they have the basic attributes the 331 descriptor does not need to be a subclass. 332 333 .. code:: python 334 335 class MyDocReader(BaseDocReader): 336 ruleDescriptorClass = MyRuleDescriptor 337 axisDescriptorClass = MyAxisDescriptor 338 sourceDescriptorClass = MySourceDescriptor 339 instanceDescriptorClass = MyInstanceDescriptor 340 341 class MyDocWriter(BaseDocWriter): 342 ruleDescriptorClass = MyRuleDescriptor 343 axisDescriptorClass = MyAxisDescriptor 344 sourceDescriptorClass = MySourceDescriptor 345 instanceDescriptorClass = MyInstanceDescriptor 346 347 myDoc = DesignSpaceDocument(KeyedDocReader, KeyedDocWriter) 348 349 ********************** 350 Document xml structure 351 ********************** 352 353 - The ``axes`` element contains one or more ``axis`` elements. 354 - The ``sources`` element contains one or more ``source`` elements. 355 - The ``instances`` element contains one or more ``instance`` elements. 356 - The ``rules`` element contains one or more ``rule`` elements. 357 - The ``lib`` element contains arbitrary data. 358 359 .. code:: xml 360 361 <?xml version='1.0' encoding='utf-8'?> 362 <designspace format="3"> 363 <axes> 364 <!-- define axes here --> 365 <axis../> 366 </axes> 367 <sources> 368 <!-- define masters here --> 369 <source../> 370 </sources> 371 <instances> 372 <!-- define instances here --> 373 <instance../> 374 </instances> 375 <rules> 376 <!-- define rules here --> 377 <rule../> 378 </rules> 379 <lib> 380 <dict> 381 <!-- store custom data here --> 382 </dict> 383 </lib> 384 </designspace> 385 386 .. 1-axis-element: 387 388 1. axis element 389 =============== 390 391 - Define a single axis 392 - Child element of ``axes`` 393 394 .. attributes-2: 395 396 Attributes 397 ---------- 398 399 - ``name``: required, string. Name of the axis that is used in the 400 location elements. 401 - ``tag``: required, string, 4 letters. Some axis tags are registered 402 in the OpenType Specification. 403 - ``minimum``: required, number. The minimum value for this axis. 404 - ``maximum``: required, number. The maximum value for this axis. 405 - ``default``: required, number. The default value for this axis. 406 - ``hidden``: optional, 0 or 1. Records whether this axis needs to be 407 hidden in interfaces. 408 409 .. code:: xml 410 411 <axis name="weight" tag="wght" minimum="1" maximum="1000" default="400"> 412 413 .. 11-labelname-element: 414 415 1.1 labelname element 416 ===================== 417 418 - Defines a human readable name for UI use. 419 - Optional for non-registered axis names. 420 - Can be localised with ``xml:lang`` 421 - Child element of ``axis`` 422 423 .. attributes-3: 424 425 Attributes 426 ---------- 427 428 - ``xml:lang``: required, string. `XML language 429 definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__ 430 431 Value 432 ----- 433 434 - The natural language name of this axis. 435 436 .. example-1: 437 438 Example 439 ------- 440 441 .. code:: xml 442 443 <labelname xml:lang="fa-IR"></labelname> 444 <labelname xml:lang="en">Wght</labelname> 445 446 .. 12-map-element: 447 448 1.2 map element 449 =============== 450 451 - Defines a single node in a series of input value / output value 452 pairs. 453 - Together these values transform the designspace. 454 - Child of ``axis`` element. 455 456 .. example-2: 457 458 Example 459 ------- 460 461 .. code:: xml 462 463 <map input="1.0" output="10.0" /> 464 <map input="400.0" output="66.0" /> 465 <map input="1000.0" output="990.0" /> 466 467 Example of all axis elements together: 468 -------------------------------------- 469 470 .. code:: xml 471 472 <axes> 473 <axis default="1" maximum="1000" minimum="0" name="weight" tag="wght"> 474 <labelname xml:lang="fa-IR"></labelname> 475 <labelname xml:lang="en">Wght</labelname> 476 </axis> 477 <axis default="100" maximum="200" minimum="50" name="width" tag="wdth"> 478 <map input="50.0" output="10.0" /> 479 <map input="100.0" output="66.0" /> 480 <map input="200.0" output="990.0" /> 481 </axis> 482 </axes> 483 484 .. 2-location-element: 485 486 2. location element 487 =================== 488 489 - Defines a coordinate in the design space. 490 - Dictionary of axisname: axisvalue 491 - Used in ``source``, ``instance`` and ``glyph`` elements. 492 493 .. 21-dimension-element: 494 495 2.1 dimension element 496 ===================== 497 498 - Child element of ``location`` 499 500 .. attributes-4: 501 502 Attributes 503 ---------- 504 505 - ``name``: required, string. Name of the axis. 506 - ``xvalue``: required, number. The value on this axis. 507 - ``yvalue``: optional, number. Separate value for anisotropic 508 interpolations. 509 510 .. example-3: 511 512 Example 513 ------- 514 515 .. code:: xml 516 517 <location> 518 <dimension name="width" xvalue="0.000000" /> 519 <dimension name="weight" xvalue="0.000000" yvalue="0.003" /> 520 </location> 521 522 .. 3-source-element: 523 524 3. source element 525 ================= 526 527 - Defines a single font that contributes to the designspace. 528 - Child element of ``sources`` 529 530 .. attributes-5: 531 532 Attributes 533 ---------- 534 535 - ``familyname``: optional, string. The family name of the source font. 536 While this could be extracted from the font data itself, it can be 537 more efficient to add it here. 538 - ``stylename``: optional, string. The style name of the source font. 539 - ``name``: required, string. A unique name that can be used to 540 identify this font if it needs to be referenced elsewhere. 541 - ``filename``: required, string. A path to the source file, relative 542 to the root path of this document. The path can be at the same level 543 as the document or lower. 544 - ``layer``: optional, string. The name of the layer in the source file. 545 If no layer attribute is given assume the foreground layer should be used. 546 547 .. 31-lib-element: 548 549 3.1 lib element 550 =============== 551 552 There are two meanings for the ``lib`` element: 553 554 1. Source lib 555 - Example: ``<lib copy="1" />`` 556 - Child element of ``source`` 557 - Defines if the instances can inherit the data in the lib of this 558 source. 559 - MutatorMath only 560 561 2. Document and instance lib 562 - Example: 563 564 .. code:: xml 565 566 <lib> 567 <dict> 568 <key>...</key> 569 <string>The contents use the PLIST format.</string> 570 </dict> 571 </lib> 572 573 - Child element of ``designspace`` and ``instance`` 574 - Contains arbitrary data about the whole document or about a specific 575 instance. 576 - Items in the dict need to use **reverse domain name notation** <https://en.wikipedia.org/wiki/Reverse_domain_name_notation>__ 577 578 .. 32-info-element: 579 580 3.2 info element 581 ================ 582 583 - ``<info copy="1" />`` 584 - Child element of ``source`` 585 - Defines if the instances can inherit the non-interpolating font info 586 from this source. 587 - MutatorMath + Varlib 588 - NOTE: **This presence of this element indicates this source is to be 589 the default font.** 590 591 .. 33-features-element: 592 593 3.3 features element 594 ==================== 595 596 - ``<features copy="1" />`` 597 - Defines if the instances can inherit opentype feature text from this 598 source. 599 - Child element of ``source`` 600 - MutatorMath only 601 602 .. 34-glyph-element: 603 604 3.4 glyph element 605 ================= 606 607 - Can appear in ``source`` as well as in ``instance`` elements. 608 - In a ``source`` element this states if a glyph is to be excluded from 609 the calculation. 610 - MutatorMath only 611 612 .. attributes-6: 613 614 Attributes 615 ---------- 616 617 - ``mute``: optional attribute, number 1 or 0. Indicate if this glyph 618 should be ignored as a master. 619 - ``<glyph mute="1" name="A"/>`` 620 - MutatorMath only 621 622 .. 35-kerning-element: 623 624 3.5 kerning element 625 =================== 626 627 - ``<kerning mute="1" />`` 628 - Can appear in ``source`` as well as in ``instance`` elements. 629 630 .. attributes-7: 631 632 Attributes 633 ---------- 634 635 - ``mute``: required attribute, number 1 or 0. Indicate if the kerning 636 data from this source is to be excluded from the calculation. 637 - If the kerning element is not present, assume ``mute=0``, yes, 638 include the kerning of this source in the calculation. 639 - MutatorMath only 640 641 .. example-4: 642 643 Example 644 ------- 645 646 .. code:: xml 647 648 <source familyname="MasterFamilyName" filename="masters/masterTest1.ufo" name="master.ufo1" stylename="MasterStyleNameOne"> 649 <lib copy="1" /> 650 <features copy="1" /> 651 <info copy="1" /> 652 <glyph mute="1" name="A" /> 653 <glyph mute="1" name="Z" /> 654 <location> 655 <dimension name="width" xvalue="0.000000" /> 656 <dimension name="weight" xvalue="0.000000" /> 657 </location> 658 </source> 659 660 .. 4-instance-element: 661 662 4. instance element 663 =================== 664 665 - Defines a single font that can be calculated with the designspace. 666 - Child element of ``instances`` 667 - For use in Varlib the instance element really only needs the names 668 and the location. The ``glyphs`` element is not required. 669 - MutatorMath uses the ``glyphs`` element to describe how certain 670 glyphs need different masters, mainly to describe the effects of 671 conditional rules in Superpolator. 672 673 .. attributes-8: 674 675 Attributes 676 ---------- 677 678 - ``familyname``: required, string. The family name of the instance 679 font. Corresponds with ``font.info.familyName`` 680 - ``stylename``: required, string. The style name of the instance font. 681 Corresponds with ``font.info.styleName`` 682 - ``name``: required, string. A unique name that can be used to 683 identify this font if it needs to be referenced elsewhere. 684 - ``filename``: string. Required for MutatorMath. A path to the 685 instance file, relative to the root path of this document. The path 686 can be at the same level as the document or lower. 687 - ``postscriptfontname``: string. Optional for MutatorMath. Corresponds 688 with ``font.info.postscriptFontName`` 689 - ``stylemapfamilyname``: string. Optional for MutatorMath. Corresponds 690 with ``styleMapFamilyName`` 691 - ``stylemapstylename``: string. Optional for MutatorMath. Corresponds 692 with ``styleMapStyleName`` 693 694 Example for varlib 695 ------------------ 696 697 .. code:: xml 698 699 <instance familyname="InstanceFamilyName" filename="instances/instanceTest2.ufo" name="instance.ufo2" postscriptfontname="InstancePostscriptName" stylemapfamilyname="InstanceStyleMapFamilyName" stylemapstylename="InstanceStyleMapStyleName" stylename="InstanceStyleName"> 700 <location> 701 <dimension name="width" xvalue="400" yvalue="300" /> 702 <dimension name="weight" xvalue="66" /> 703 </location> 704 <kerning /> 705 <info /> 706 <lib> 707 <dict> 708 <key>com.coolDesignspaceApp.specimenText</key> 709 <string>Hamburgerwhatever</string> 710 </dict> 711 </lib> 712 </instance> 713 714 .. 41-glyphs-element: 715 716 4.1 glyphs element 717 ================== 718 719 - Container for ``glyph`` elements. 720 - Optional 721 - MutatorMath only. 722 723 .. 42-glyph-element: 724 725 4.2 glyph element 726 ================= 727 728 - Child element of ``glyphs`` 729 - May contain a ``location`` element. 730 731 .. attributes-9: 732 733 Attributes 734 ---------- 735 736 - ``name``: string. The name of the glyph. 737 - ``unicode``: string. Unicode values for this glyph, in hexadecimal. 738 Multiple values should be separated with a space. 739 - ``mute``: optional attribute, number 1 or 0. Indicate if this glyph 740 should be supressed in the output. 741 742 .. 421-note-element: 743 744 4.2.1 note element 745 ================== 746 747 - String. The value corresponds to glyph.note in UFO. 748 749 .. 422-masters-element: 750 751 4.2.2 masters element 752 ===================== 753 754 - Container for ``master`` elements 755 - These ``master`` elements define an alternative set of glyph masters 756 for this glyph. 757 758 .. 4221-master-element: 759 760 4.2.2.1 master element 761 ====================== 762 763 - Defines a single alternative master for this glyph. 764 765 4.3 Localised names for instances 766 ================================= 767 768 Localised names for instances can be included with these simple elements 769 with an ``xml:lang`` attribute: 770 `XML language definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__ 771 772 - stylename 773 - familyname 774 - stylemapstylename 775 - stylemapfamilyname 776 777 .. example-5: 778 779 Example 780 ------- 781 782 .. code:: xml 783 784 <stylename xml:lang="fr">Demigras</stylename> 785 <stylename xml:lang="ja"></stylename> 786 <familyname xml:lang="fr">Montserrat</familyname> 787 <familyname xml:lang="ja"></familyname> 788 <stylemapstylename xml:lang="de">Standard</stylemapstylename> 789 <stylemapfamilyname xml:lang="de">Montserrat Halbfett</stylemapfamilyname> 790 <stylemapfamilyname xml:lang="ja"> SemiBold</stylemapfamilyname> 791 792 .. attributes-10: 793 794 Attributes 795 ---------- 796 797 - ``glyphname``: the name of the alternate master glyph. 798 - ``source``: the identifier name of the source this master glyph needs 799 to be loaded from 800 801 .. example-6: 802 803 Example 804 ------- 805 806 .. code:: xml 807 808 <instance familyname="InstanceFamilyName" filename="instances/instanceTest2.ufo" name="instance.ufo2" postscriptfontname="InstancePostscriptName" stylemapfamilyname="InstanceStyleMapFamilyName" stylemapstylename="InstanceStyleMapStyleName" stylename="InstanceStyleName"> 809 <location> 810 <dimension name="width" xvalue="400" yvalue="300" /> 811 <dimension name="weight" xvalue="66" /> 812 </location> 813 <glyphs> 814 <glyph name="arrow2" /> 815 <glyph name="arrow" unicode="0x4d2 0x4d3"> 816 <location> 817 <dimension name="width" xvalue="100" /> 818 <dimension name="weight" xvalue="120" /> 819 </location> 820 <note>A note about this glyph</note> 821 <masters> 822 <master glyphname="BB" source="master.ufo1"> 823 <location> 824 <dimension name="width" xvalue="20" /> 825 <dimension name="weight" xvalue="20" /> 826 </location> 827 </master> 828 </masters> 829 </glyph> 830 </glyphs> 831 <kerning /> 832 <info /> 833 <lib> 834 <dict> 835 <key>com.coolDesignspaceApp.specimenText</key> 836 <string>Hamburgerwhatever</string> 837 </dict> 838 </lib> 839 </instance> 840 841 .. 50-rules-element: 842 843 5.0 rules element 844 ================= 845 846 - Container for ``rule`` elements 847 - The rules are evaluated in this order. 848 849 .. 51-rule-element: 850 851 5.1 rule element 852 ================ 853 854 - Defines a named rule. 855 - Each ``rule`` element contains one or more ``conditionset`` elements. 856 - Only one ``conditionset`` needs to be true to trigger the rule. 857 - All conditions in a ``conditionset`` must be true to make the ``conditionset`` true. 858 - 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. 859 - A rule element needs to contain one or more ``sub`` elements in order to be compiled to a variable font. 860 - Rules without sub elements should be ignored when compiling a font. 861 - For authoring tools it might be necessary to save designspace files without ``sub`` elements just because the work is incomplete. 862 863 .. attributes-11: 864 865 Attributes 866 ---------- 867 868 - ``name``: optional, string. A unique name that can be used to 869 identify this rule if it needs to be referenced elsewhere. The name 870 is not important for compiling variable fonts. 871 872 5.1.1 conditionset element 873 ======================= 874 875 - Child element of ``rule`` 876 - Contains one or more ``condition`` elements. 877 878 .. 512-condition-element: 879 880 5.1.2 condition element 881 ======================= 882 883 - Child element of ``conditionset`` 884 - Between the ``minimum`` and ``maximum`` this rule is ``True``. 885 - If ``minimum`` is not available, assume it is ``axis.minimum``. 886 - If ``maximum`` is not available, assume it is ``axis.maximum``. 887 - The condition must contain at least a minimum or maximum or both. 888 889 .. attributes-12: 890 891 Attributes 892 ---------- 893 894 - ``name``: string, required. Must match one of the defined ``axis`` 895 name attributes. 896 - ``minimum``: number, required*. The low value. 897 - ``maximum``: number, required*. The high value. 898 899 .. 513-sub-element: 900 901 5.1.3 sub element 902 ================= 903 904 - Child element of ``rule``. 905 - Defines which glyph to replace when the rule evaluates to **True**. 906 907 .. attributes-13: 908 909 Attributes 910 ---------- 911 912 - ``name``: string, required. The name of the glyph this rule looks 913 for. 914 - ``with``: string, required. The name of the glyph it is replaced 915 with. 916 917 .. example-7: 918 919 Example 920 ------- 921 922 Example with an implied ``conditionset``. Here the conditions are not 923 contained in a conditionset. 924 925 .. code:: xml 926 927 <rules> 928 <rule name="named.rule.1"> 929 <condition minimum="250" maximum="750" name="weight" /> 930 <condition minimum="50" maximum="100" name="width" /> 931 <sub name="dollar" with="dollar.alt"/> 932 </rule> 933 </rules> 934 935 Example with ``conditionsets``. All conditions in a conditionset must be true. 936 937 .. code:: xml 938 939 <rules> 940 <rule name="named.rule.2"> 941 <conditionset> 942 <condition minimum="250" maximum="750" name="weight" /> 943 <condition minimum="50" maximum="100" name="width" /> 944 </conditionset> 945 <conditionset> 946 <condition ... /> 947 <condition ... /> 948 </conditionset> 949 <sub name="dollar" with="dollar.alt"/> 950 </rule> 951 </rules> 952 953 .. 6-notes: 954 955 6 Notes 956 ======= 957 958 Paths and filenames 959 ------------------- 960 961 A designspace file needs to store many references to UFO files. 962 963 - designspace files can be part of versioning systems and appear on 964 different computers. This means it is not possible to store absolute 965 paths. 966 - So, all paths are relative to the designspace document path. 967 - Using relative paths allows designspace files and UFO files to be 968 **near** each other, and that they can be **found** without enforcing 969 one particular structure. 970 - The **filename** attribute in the ``SourceDescriptor`` and 971 ``InstanceDescriptor`` classes stores the preferred relative path. 972 - The **path** attribute in these objects stores the absolute path. It 973 is calculated from the document path and the relative path in the 974 filename attribute when the object is created. 975 - Only the **filename** attribute is written to file. 976 - Both **filename** and **path** must use forward slashes (``/``) as 977 path separators, even on Windows. 978 979 Right before we save we need to identify and respond to the following 980 situations: 981 982 In each descriptor, we have to do the right thing for the filename 983 attribute. Before writing to file, the ``documentObject.updatePaths()`` 984 method prepares the paths as follows: 985 986 **Case 1** 987 988 :: 989 990 descriptor.filename == None 991 descriptor.path == None 992 993 **Action** 994 995 - write as is, descriptors will not have a filename attr. Useless, but 996 no reason to interfere. 997 998 **Case 2** 999 1000 :: 1001 1002 descriptor.filename == "../something" 1003 descriptor.path == None 1004 1005 **Action** 1006 1007 - write as is. The filename attr should not be touched. 1008 1009 **Case 3** 1010 1011 :: 1012 1013 descriptor.filename == None 1014 descriptor.path == "~/absolute/path/there" 1015 1016 **Action** 1017 1018 - calculate the relative path for filename. We're not overwriting some 1019 other value for filename, it should be fine. 1020 1021 **Case 4** 1022 1023 :: 1024 1025 descriptor.filename == '../somewhere' 1026 descriptor.path == "~/absolute/path/there" 1027 1028 **Action** 1029 1030 - There is a conflict between the given filename, and the path. The 1031 difference could have happened for any number of reasons. Assuming 1032 the values were not in conflict when the object was created, either 1033 could have changed. We can't guess. 1034 - Assume the path attribute is more up to date. Calculate a new value 1035 for filename based on the path and the document path. 1036 1037 Recommendation for editors 1038 -------------------------- 1039 1040 - If you want to explicitly set the **filename** attribute, leave the 1041 path attribute empty. 1042 - If you want to explicitly set the **path** attribute, leave the 1043 filename attribute empty. It will be recalculated. 1044 - Use ``documentObject.updateFilenameFromPath()`` to explicitly set the 1045 **filename** attributes for all instance and source descriptors. 1046 1047 .. 7-common-lib-key-registry: 1048 1049 7 Common Lib Key Registry 1050 ========================= 1051 1052 public.skipExportGlyphs 1053 ----------------------- 1054 1055 This lib key works the same as the UFO lib key with the same name. The 1056 difference is that applications using a Designspace as the corner stone of the 1057 font compilation process should use the lib key in that Designspace instead of 1058 any of the UFOs. If the lib key is empty or not present in the Designspace, all 1059 glyphs should be exported, regardless of what the same lib key in any of the 1060 UFOs says. 1061 1062 .. 8-this-document: 1063 1064 8 This document 1065 =============== 1066 1067 - The package is rather new and changes are to be expected. 1068
