1################################# 2DesignSpaceDocument Specification 3################################# 4 5An 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 12A 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 23The DesignSpaceDocument object can read and write ``.designspace`` data. 24It imports the axes, sources and instances to very basic **descriptor** 25objects that store the data in attributes. Data is added to the document 26by creating such descriptor objects, filling them with data and then 27adding them to the document. This makes it easy to integrate this object 28in different contexts. 29 30The **DesignSpaceDocument** object can be subclassed to work with 31different 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********** 43Validation 44********** 45 46Some validation is done when reading. 47 48Axes 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 60Default 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************ 74Localisation 75************ 76 77Some of the descriptors support localised names. The names are stored in 78dictionaries using the language code as key. That means that there are 79now two places to store names: the old attribute and the new localised 80dictionary, ``obj.stylename`` and ``obj.localisedStyleName['en']``. 81 82***** 83Rules 84***** 85 86Rules describe designspace areas in which one glyph should be replaced by another. 87A rule has a name and a number of conditionsets. The rule also contains a list of 88glyphname 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 92The ``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 94UFO 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********** 110Python API 111********** 112 113SourceDescriptor object 114======================= 115 116Attributes 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 180InstanceDescriptor object 181========================= 182 183.. attributes-1: 184 185Attributes 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 225Methods 226------- 227 228These 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 239Example 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 266AxisDescriptor 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"Wéíght" 302 a1.map = [(1.0, 10.0), (400.0, 66.0), (1000.0, 990.0)] 303 304RuleDescriptor 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 325Subclassing descriptors 326======================= 327 328The DesignSpaceDocument can take subclassed Reader and Writer objects. 329This allows you to work with your own descriptors. You could subclass 330the descriptors. But as long as they have the basic attributes the 331descriptor 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********************** 350Document 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 3881. axis element 389=============== 390 391- Define a single axis 392- Child element of ``axes`` 393 394.. attributes-2: 395 396Attributes 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 4151.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 425Attributes 426---------- 427 428- ``xml:lang``: required, string. `XML language 429 definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__ 430 431Value 432----- 433 434- The natural language name of this axis. 435 436.. example-1: 437 438Example 439------- 440 441.. code:: xml 442 443 <labelname xml:lang="fa-IR">قطر</labelname> 444 <labelname xml:lang="en">Wéíght</labelname> 445 446.. 12-map-element: 447 4481.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 458Example 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 467Example 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">Wéíght</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 4862. 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 4952.1 dimension element 496===================== 497 498- Child element of ``location`` 499 500.. attributes-4: 501 502Attributes 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 512Example 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 5243. source element 525================= 526 527- Defines a single font that contributes to the designspace. 528- Child element of ``sources`` 529 530.. attributes-5: 531 532Attributes 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 5493.1 lib element 550=============== 551 552There are two meanings for the ``lib`` element: 553 5541. 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 5612. 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 5803.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 5933.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 6043.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 614Attributes 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 6243.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 632Attributes 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 643Example 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 6624. 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 675Attributes 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 694Example 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 7164.1 glyphs element 717================== 718 719- Container for ``glyph`` elements. 720- Optional 721- MutatorMath only. 722 723.. 42-glyph-element: 724 7254.2 glyph element 726================= 727 728- Child element of ``glyphs`` 729- May contain a ``location`` element. 730 731.. attributes-9: 732 733Attributes 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 7444.2.1 note element 745================== 746 747- String. The value corresponds to glyph.note in UFO. 748 749.. 422-masters-element: 750 7514.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 7604.2.2.1 master element 761====================== 762 763- Defines a single alternative master for this glyph. 764 7654.3 Localised names for instances 766================================= 767 768Localised names for instances can be included with these simple elements 769with 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 779Example 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 794Attributes 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 803Example 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 8435.0 rules element 844================= 845 846- Container for ``rule`` elements 847- The rules are evaluated in this order. 848 849.. 51-rule-element: 850 8515.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 865Attributes 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 8725.1.1 conditionset element 873======================= 874 875- Child element of ``rule`` 876- Contains one or more ``condition`` elements. 877 878.. 512-condition-element: 879 8805.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 891Attributes 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 9015.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 909Attributes 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 919Example 920------- 921 922Example with an implied ``conditionset``. Here the conditions are not 923contained 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 935Example 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 9556 Notes 956======= 957 958Paths and filenames 959------------------- 960 961A 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 979Right before we save we need to identify and respond to the following 980situations: 981 982In each descriptor, we have to do the right thing for the filename 983attribute. Before writing to file, the ``documentObject.updatePaths()`` 984method 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 1037Recommendation 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 10497 Common Lib Key Registry 1050========================= 1051 1052public.skipExportGlyphs 1053----------------------- 1054 1055This lib key works the same as the UFO lib key with the same name. The 1056difference is that applications using a Designspace as the corner stone of the 1057font compilation process should use the lib key in that Designspace instead of 1058any of the UFOs. If the lib key is empty or not present in the Designspace, all 1059glyphs should be exported, regardless of what the same lib key in any of the 1060UFOs says. 1061 1062.. 8-this-document: 1063 10648 This document 1065=============== 1066 1067- The package is rather new and changes are to be expected. 1068