1.. _document-xml-structure: 2 3********************** 4Document XML structure 5********************** 6 7.. sectnum:: 8 :start: 2 9.. Note: impossible with Sphinx to avoid numbering the document title 10.. See this issue: https://github.com/sphinx-doc/sphinx/issues/4628 11 12.. contents:: Table of contents (levels match the document structure) 13 :local: 14 15======== 16Overview 17======== 18 19 20.. code:: xml 21 22 <?xml version='1.0' encoding='utf-8'?> 23 <designspace format="5.1"> 24 <axes> 25 <!-- define axes here --> 26 <axis... /> 27 <mappings> 28 <!-- define axis mappings here --> 29 <!-- New in version 5.1 --> 30 <mapping... /> 31 </mappings> 32 </axes> 33 <labels> 34 <!-- define STAT format 4 labels here --> 35 <!-- New in version 5.0 --> 36 <label... /> 37 </labels> 38 <sources> 39 <!-- define masters here --> 40 <source... /> 41 </sources> 42 <variable-fonts> 43 <!-- define variable fonts here --> 44 <!-- New in version 5.0 --> 45 <variable-font... /> 46 </variable-fonts> 47 <instances> 48 <!-- define instances here --> 49 <instance... /> 50 </instances> 51 <rules> 52 <!-- define rules here --> 53 <rule... /> 54 </rules> 55 <lib> 56 <dict> 57 <!-- store custom data here --> 58 </dict> 59 </lib> 60 </designspace> 61 62================== 63``<axes>`` element 64================== 65 66The ``<axes>`` element contains one or more ``<axis>`` elements. 67 68.. rubric:: Attributes 69 70- ``elidedfallbackname``: optional, string. 71 STAT Style Attributes Header field ``elidedFallbackNameID``. 72 See: `OTSpec STAT Style Attributes Header 73 <https://docs.microsoft.com/en-us/typography/opentype/spec/stat#style-attributes-header>`_ 74 75 .. versionadded:: 5.0 76 77 78``<axis>`` element 79================== 80 81- Define a single axis 82- Child element of ``axes`` 83- The axis can be either continuous (as in version 4.0) or discrete (new in version 5.0). 84 Discrete axes have a list of values instead of a range minimum and maximum. 85 86 87.. rubric:: Attributes 88 89- ``name``: required, string. Name of the axis that is used in the 90 location elements. 91- ``tag``: required, string, 4 letters. Some axis tags are registered 92 in the OpenType Specification. 93- ``default``: required, number. The default value for this axis, in user space coordinates. 94- ``hidden``: optional, 0 or 1. Records whether this axis needs to be 95 hidden in interfaces. 96 97For a continuous axis: 98 - ``minimum``: required, number. The minimum value for this axis, in user space coordinates. 99 - ``maximum``: required, number. The maximum value for this axis, in user space coordinates. 100 101For a discrete axis: 102 - ``values``: required, space-separated numbers. The exhaustive list of possible values along this axis. 103 104 .. versionadded:: 5.0 105 106 107.. rubric:: Example 108 109.. code:: xml 110 111 <axis name="weight" tag="wght" minimum="1" maximum="1000" default="400"> 112 113 <!-- 114 Discrete axes provide a list of discrete values. 115 No interpolation is allowed between these. 116 --> 117 <axis name="Italic" tag="ital" default="0" values="0 1"> 118 119 120.. _labelname: 121 122``<labelname>`` element (axis) 123------------------------------ 124 125- Defines a human readable name for UI use. 126- Optional for non-registered axis names. 127- Can be localised with ``xml:lang`` 128- Child element of ``<axis>`` or ``<label>`` 129 130 131.. rubric:: Attributes 132 133- ``xml:lang``: required, string. `XML language 134 definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__ 135 136 137.. rubric:: Value 138 139- The natural language name of this axis or STAT label. 140 141 142.. rubric:: Example 143 144.. code:: xml 145 146 <labelname xml:lang="fa-IR">قطر</labelname> 147 <labelname xml:lang="en">Wéíght</labelname> 148 149 150``<map>`` element 151----------------- 152 153- Defines a single node in a series of input value (user space coordinate) 154 to output value (designspace coordinate) pairs. 155- Together these values transform the designspace. 156- Child of ``<axis>`` element. 157 158.. rubric:: Example 159 160.. code:: xml 161 162 <map input="1.0" output="10.0" /> 163 <map input="400.0" output="66.0" /> 164 <map input="1000.0" output="990.0" /> 165 166 167``<labels>`` element (axis) 168--------------------------- 169 170The ``<labels>`` element contains one or more ``<label>`` elements, and can 171indicate this axis' STAT ordering. 172 173.. versionadded:: 5.0 174 175.. rubric:: Attributes 176 177- ``ordering``: optional, int, default: natural position of this axis in the list 178 of axes. STAT table field ``axisOrdering`` for this axis. 179 180 See: `OTSpec STAT Axis Record <https://docs.microsoft.com/en-us/typography/opentype/spec/stat#axis-records>`_ 181 182``<label>`` element (axis) 183.......................... 184 185- Define STAT format 1, 2, 3 labels for the locations on this axis. 186- The axis can have several child ``<label>`` elements, one for each STAT entry. 187- This ``<label>`` element can have several ``<labelname>`` child elements, 188 to provide translations of its ``name`` attribute. 189 190.. versionadded:: 5.0 191 192.. rubric:: Attributes 193 194- ``name``: required, string. the name of this label 195- ``elidable``: optional, boolean, default: false. STAT flag ``ELIDABLE_AXIS_VALUE_NAME``. 196- ``oldersibling``: optional, boolean, default: false. STAT flag ``OLDER_SIBLING_FONT_ATTRIBUTE``. 197 198 See: `OTSpec STAT Flags <https://docs.microsoft.com/en-us/typography/opentype/spec/stat#flags>`_ 199 200Depending on the intended target STAT format, use a combination of the following 201field, all in user coordinates. Check the following table for the format 202correspondences. 203 204- ``uservalue``: (required) STAT field ``value`` (format 1, 3) or ``nominalValue`` (format 2). 205- ``userminimum``: STAT field ``rangeMinValue`` (format 2). 206- ``usermaximum``: STAT field ``rangeMaxValue`` (format 2). 207- ``linkeduservalue``: STAT field ``linkedValue`` (format 3). 208 209=========== ========= =========== =========== =============== 210STAT Format uservalue userminimum usermaximum linkeduservalue 211=========== ========= =========== =========== =============== 2121 ✅ ❌ ❌ ❌ 2132 ✅ ✅ ✅ ❌ 2143 ✅ ❌ ❌ ✅ 215=========== ========= =========== =========== =============== 216 217.. rubric:: Example 218 219.. code:: xml 220 221 <label userminimum="200" uservalue="200" usermaximum="250" name="Extra Light"> 222 <labelname xml:lang="de">Extraleicht</labelname> 223 <labelname xml:lang="fr">Extra léger</labelname> 224 </label> 225 <label userminimum="350" uservalue="400" usermaximum="450" name="Regular" elidable="true" /> 226 227 228``<labelname>`` element (axis STAT label) 229,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 230 231User-facing translations of this STAT label. Keyed by ``xml:lang`` code. 232 233.. versionadded:: 5.0 234 235Same attribute and value as :ref:`the axis' \<labelname\> element <labelname>`. 236 237 238Example of all axis elements together 239===================================== 240 241.. code:: xml 242 243 <axes elidedfallbackname="Regular"> 244 <axis default="1" maximum="1000" minimum="0" name="weight" tag="wght"> 245 <labelname xml:lang="fa-IR">قطر</labelname> 246 <labelname xml:lang="en">Wéíght</labelname> 247 <labels> 248 <label userminimum="200" uservalue="200" usermaximum="250" name="Extra Light"> 249 <labelname xml:lang="de">Extraleicht</labelname> 250 <labelname xml:lang="fr">Extra léger</labelname> 251 </label> 252 <label userminimum="350" uservalue="400" usermaximum="450" name="Regular" elidable="true" /> 253 </labels> 254 </axis> 255 <axis default="100" maximum="200" minimum="50" name="width" tag="wdth"> 256 <map input="50.0" output="10.0" /> 257 <map input="100.0" output="66.0" /> 258 <map input="200.0" output="990.0" /> 259 </axis> 260 </axes> 261 262 263``<mappings>`` element 264====================== 265 266- Define an axis mappings group. 267- Child element of ``axes`` 268 269.. rubric:: Attributes 270 271- ``description``: optional, string. the description of this mappings group 272 273 .. versionadded:: 5.2 274 275 276``<mapping>`` element 277--------------------- 278 279- Defines an axis mapping. 280- Child element of ``<mappings>`` 281 282.. rubric:: Attributes 283 284- ``description``: optional, string. the description of this mapping 285 286 .. versionadded:: 5.2 287 288 289``<input>`` element 290................... 291 292- Defines the input location of an axis mapping. 293- Child element of ``<mapping>`` 294- Contains one or more ``<dimension>`` elements with designspace locations. 295 296 .. versionadded:: 5.1 297 298 299``<output>`` element 300................... 301 302- Defines the output location of an axis mapping. 303- Child element of ``<mapping>`` 304- Contains one or more ``<dimension>`` elements with designspace locations. 305 306 .. versionadded:: 5.1 307 308 309Example of all mappings elements together 310========================================= 311 312.. code:: xml 313 314 <mappings> 315 <mapping> 316 <input> 317 <dimension name="weight" xvalue="900"/> 318 <dimension name="width" xvalue="150"/> 319 </input> 320 <output> 321 <dimension name="weight" xvalue="870"/> 322 </output> 323 </mapping> 324 </mappings> 325 326 327================================ 328``<labels>`` element (top-level) 329================================ 330 331The ``<labels>`` element contains one or more ``<label>`` elements. 332 333.. versionadded:: 5.0 334 335``<label>`` element (top-level) 336=============================== 337 338- Define STAT format 4 labels for a free-standing location. 339- The designspace can have several top-level ``<label>`` elements, one for each 340 STAT format 4 entry. 341- This ``<label>`` element must have a child ``<location>`` element that 342 represents the location to which the label applies. 343- This ``<label>`` element may have several child ``<labelname>`` elements to 344 provide translations of its ``name`` attribute. 345 346 347See: `OTSpec STAT Axis value table, format 4 <https://docs.microsoft.com/en-us/typography/opentype/spec/stat#axis-value-table-format-4>`_ 348 349.. versionadded:: 5.0 350 351.. rubric:: Attributes 352 353- ``name``: required, string. the name of this label 354- ``elidable``: optional, boolean, default: false. STAT flag ``ELIDABLE_AXIS_VALUE_NAME``. 355- ``oldersibling``: optional, boolean, default: false. STAT flag ``OLDER_SIBLING_FONT_ATTRIBUTE``. 356 357 See: `OTSpec STAT Flags <https://docs.microsoft.com/en-us/typography/opentype/spec/stat#flags>`_ 358 359 360.. _location: 361 362``<location>`` element (top-level STAT label) 363--------------------------------------------- 364 365- Defines a coordinate in either user or design space. 366- Encodes a dictionary of ``{ axisname: axisvalue }``. 367- Also used in ``<source>``, ``<instance>`` and ``<glyph>`` elements. 368- This ``<location>`` element must have one or more child ``<dimension>`` 369 elements. 370 371.. _dimension: 372 373``<dimension>`` element 374....................... 375 376- Child element of ``<location>``, ``input``, or ``output`` elements 377 378.. rubric:: Attributes 379 380- ``name``: required, string. Name of the axis. 381 382Depending on whether you're representing a location in user or design coordinates, 383provide one of the attributes below. 384 385For user-space coordinates: 386 387- ``uservalue``: required, number. The value on this axis in user coordinates. 388 389 .. versionadded:: 5.0 390 391For design-space coordinates: 392 393- ``xvalue``: required, number. The value on this axis in design coordinates. 394- ``yvalue``: optional, number. Separate value for anisotropic interpolations. 395 396 397.. rubric:: Example 398 399.. code:: xml 400 401 <location> 402 <dimension name="Width" uservalue="125" /> 403 <dimension name="Weight" xvalue="10" yvalue="20.5" /> 404 </location> 405 406 407``<labelname>`` element (top-level STAT label) 408---------------------------------------------- 409 410User-facing translations of this STAT label. Keyed by ``xml:lang`` code. 411 412.. versionadded:: 5.0 413 414Same attribute and value as :ref:`the axis' \<labelname\> element <labelname>`. 415 416 417.. _rules-element: 418 419=================== 420``<rules>`` element 421=================== 422 423The ``<rules>`` element contains one or more ``<rule>`` elements. 424 425The rules are evaluated in this order. 426 427Rules describe designspace areas in which one glyph should be replaced by another. 428A rule has a name and a number of conditionsets. The rule also contains a list of 429glyphname pairs: the glyphs that need to be substituted. For a rule to be triggered 430**only one** of the conditionsets needs to be true, ``OR``. Within a conditionset 431**all** conditions need to be true, ``AND``. 432 433 434.. rubric:: Attributes 435 436- ``processing``: flag, optional. Valid values are [``first``, ``last``]. This 437 flag indicates whether the substitution rules should be applied before or after 438 other glyph substitution features. 439 440 - If no ``processing`` attribute is given, interpret as ``first``, and put 441 the substitution rule in the ``rvrn`` feature. 442 - If ``processing`` is ``last``, put it in ``rclt``. 443 - The default is ``first``. For new projects, you probably want ``last``. 444 See the following issues for more information: 445 `fontTools#1371 <https://github.com/fonttools/fonttools/issues/1371#issuecomment-590214572>`__ 446 `fontTools#2050 <https://github.com/fonttools/fonttools/issues/2050#issuecomment-678691020>`__ 447 - If you want to use a different feature(s) altogether, e.g. ``calt``, 448 use the lib key ``com.github.fonttools.varLib.featureVarsFeatureTag``. 449 450 .. code:: xml 451 452 <lib> 453 <dict> 454 <key>com.github.fonttools.varLib.featureVarsFeatureTag</key> 455 <string>calt</string> 456 </dict> 457 </lib> 458 459 This can also take a comma-separated list of feature tags, e.g. ``salt,ss01``, 460 if you wish the same rules to be applied with several features. 461 462 463 464``<rule>`` element 465================== 466 467- Defines a named rule. 468- Each ``<rule>`` element contains one or more ``<conditionset>`` elements. 469- **Only one** ``<conditionset>`` needs to be true to trigger the rule (logical OR). An empty condition set is considered to be true, as in, the rule will be always-on. 470- **All** conditions in a ``<conditionset>`` must be true to make the ``<conditionset>`` true. (logical AND) 471- 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. 472- A rule element needs to contain one or more ``<sub>`` elements in order to be compiled to a variable font. 473- Rules without sub elements should be ignored when compiling a font. 474- For authoring tools it might be necessary to save designspace files without ``<sub>`` elements just because the work is incomplete. 475 476 477.. rubric:: Attributes 478 479- ``name``: optional, string. A unique name that can be used to 480 identify this rule if it needs to be referenced elsewhere. The name 481 is not important for compiling variable fonts. 482 483``<conditionset>`` element 484-------------------------- 485 486- Child element of ``<rule>`` 487- Contains zero or more ``<condition>`` elements. 488 489 490``<condition>`` element 491....................... 492 493- Child element of ``<conditionset>`` 494- Between the ``minimum`` and ``maximum`` this condition is ``True``. 495- ``minimum`` and ``maximum`` are in designspace coordinates. 496- If ``minimum`` is not available, assume it is ``axis.minimum``, mapped to designspace coordinates. 497- If ``maximum`` is not available, assume it is ``axis.maximum``, mapped to designspace coordinates. 498- The condition must contain at least a minimum or maximum or both. 499 500 501.. rubric:: Attributes 502 503- ``name``: string, required. Must match one of the defined ``axis`` 504 name attributes. 505- ``minimum``: number, required*. The low value, in design coordinates. 506- ``maximum``: number, required*. The high value, in design coordinates. 507 508.. If you want to specify the condition limits in design coordinates: 509 510.. If you want to specify the condition limits in user coordinates: 511 512.. - ``userminimum``: number, required*. The low value, in design coordinates. 513.. - ``usermaximum``: number, required*. The high value, in design coordinates. 514 515``<sub>`` element 516----------------- 517 518- Child element of ``<rule>``. 519- Defines which glyph to replace when the rule evaluates to **True**. 520- 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**. 521 522 523.. rubric:: Attributes 524 525- ``name``: string, required. The name of the glyph this rule looks 526 for. 527- ``with``: string, required. The name of the glyph it is replaced 528 with. 529 530 531.. rubric:: Example 532 533Example with an implied ``<conditionset>``. Here the conditions are not 534contained in a conditionset. 535 536.. code:: xml 537 538 <rules processing="last"> 539 <rule name="named.rule.1"> 540 <condition minimum="250" maximum="750" name="weight" /> 541 <condition minimum="50" maximum="100" name="width" /> 542 <sub name="dollar" with="dollar.alt"/> 543 </rule> 544 </rules> 545 546Example with ``<conditionsets>``. All conditions in a conditionset must be true. 547 548.. code:: xml 549 550 <rules> 551 <rule name="named.rule.2"> 552 <conditionset> 553 <condition minimum="250" maximum="750" name="weight" /> 554 <condition minimum="50" maximum="100" name="width" /> 555 </conditionset> 556 <conditionset> 557 <condition... /> 558 <condition... /> 559 </conditionset> 560 <sub name="dollar" with="dollar.alt"/> 561 </rule> 562 </rules> 563 564 565===================== 566``<sources>`` element 567===================== 568 569The ``<sources>`` element contains one or more ``<source>`` elements. 570 571 572``<source>`` element 573==================== 574 575- Defines a single font or layer that contributes to the designspace. 576- Child element of ``<sources>`` 577- Location in designspace coordinates. 578 579 580.. rubric:: Attributes 581 582- ``familyname``: optional, string. The family name of the source font. 583 While this could be extracted from the font data itself, it can be 584 more efficient to add it here. 585- ``stylename``: optional, string. The style name of the source font. 586- ``name``: optional, string. A unique name that can be used to 587 identify this font if it needs to be referenced elsewhere. 588- ``filename``: required, string. A path to the source file, relative 589 to the root path of this document. The path can be at the same level 590 as the document or lower. 591- ``layer``: optional, string. The name of the layer in the source file. 592 If no layer attribute is given assume the foreground layer should be used. 593 594 595``<familyname>`` element: localised names for sources 596----------------------------------------------------- 597 598Localised family names for sources can be included with this ``<familyname>`` 599element with an ``xml:lang`` attribute: 600`XML language definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__ 601 602.. versionadded:: 5.0 603 604.. rubric:: Example 605 606.. code:: xml 607 608 <familyname xml:lang="fr">Montserrat</familyname> 609 <familyname xml:lang="ja">モンセラート</familyname> 610 611 612``<location>`` element (source) 613------------------------------- 614 615Defines the coordinates of this source in the design space. 616 617.. seealso:: :ref:`Full documentation of the \<location\> element <location>` 618 619 620``<dimension>`` element (source) 621................................ 622 623.. seealso:: :ref:`Full documentation of the \<dimension\> element <dimension>` 624 625 626``<lib>`` element (source) 627-------------------------- 628 629- Example: ``<lib copy="1" />`` 630- Child element of ``<source>`` 631- Defines if the instances can inherit the data in the lib of this source. 632- MutatorMath only. 633 634.. deprecated:: 5.0 635 636.. note:: 637 638 Don't confuse with other ``<lib>`` elements which allow storing 639 arbitrary data. Sources don't have such a ``<lib>`` because usually the 640 backing UFO file has one itself. 641 642 643``<info>`` element 644------------------ 645 646- Example: ``<info copy="1" />`` 647- Child element of ``<source>`` 648- Defines if the instances can inherit the non-interpolating font info 649 from this source. 650- MutatorMath only. 651 652.. deprecated:: 5.0 653 654 655``<features>`` element 656---------------------- 657 658- Example: ``<features copy="1" />`` 659- Defines if the instances can inherit opentype feature text from this 660 source. 661- Child element of ``<source>`` 662- MutatorMath only. 663 664.. deprecated:: 5.0 665 666 667``<glyph>`` element (source) 668---------------------------- 669 670- Example: ``<glyph mute="1" name="A"/>`` 671- In a ``<source>`` element this states if a glyph is to be excluded from 672 the calculation. 673- MutatorMath only. 674 675.. rubric:: Attributes 676 677- ``mute``: optional attribute, number 1 or 0. Indicate if this glyph 678 should be ignored as a master. 679 680.. note:: 681 682 Do not confuse with the ``<glyph>`` element in instances, which achieves 683 something different. 684 685 686.. _kerning_source: 687 688``<kerning>`` element (source) 689------------------------------ 690 691- Example: ``<kerning mute="1" />`` 692- Can appear in ``<source>`` as well as in ``<instance>`` elements. 693- MutatorMath only. 694 695.. rubric:: Attributes 696 697- ``mute``: required attribute, number 1 or 0. Indicate if the kerning 698 data from this source is to be excluded from the calculation. 699 700 - If the kerning element is not present, assume ``mute=0``, yes, 701 include the kerning of this source in the calculation. 702 703 704.. rubric:: Example 705 706.. code:: xml 707 708 <source familyname="MasterFamilyName" filename="masters/masterTest1.ufo" name="master.ufo1" stylename="MasterStyleNameOne"> 709 <location> 710 <dimension name="width" xvalue="0.000000" /> 711 <dimension name="weight" xvalue="0.000000" /> 712 </location> 713 <glyph mute="1" name="A" /> 714 <glyph mute="1" name="Z" /> 715 </source> 716 717 718============================ 719``<variable-fonts>`` element 720============================ 721 722The ``<variable-fonts>`` element contains one or more ``<variable-font>`` elements. 723 724.. versionadded:: 5.0 725 726 727``<variable-font>`` element 728=========================== 729 730- Child of ``<variable-fonts>`` 731- Describe a variable font that can be built from an interpolating subset of 732 the design space. 733- The document may have zero to many variable fonts. 734 735 - If no variable fonts are defined, and all the axes are continuous, then we 736 assume, as in version 4 of the format, that the whole document describes 737 one variable font covering the whole space. 738 739- Each variable font covers a subset of the whole designspace, defined using 740 ``<axis-subset>`` elements. 741- Each variable font can have custom associated data using a ``<lib>`` element. 742 743.. versionadded:: 5.0 744 745.. rubric:: Attributes 746 747- ``name``: string, required. Each variable font has a name, that can be 748 used by build tools to refer to the font that gets built from this element. 749- ``filename``: string, optional. This filename will be used by tools to decide 750 where to store the built font on the disk. If not given, a filename can be 751 computed from the ``name``. The filename may include an extension (e.g. 752 `.ttf`) and the build tools can replace that extension with another (e.g. 753 `.otf` or `.woff2`) as needed. 754 755.. rubric:: Example 756 757.. code:: xml 758 759 <variable-font name="MyFontVF_Italic"> 760 <axis-subsets> 761 <axis-subset name="Weight"/> 762 <axis-subset name="Italic" uservalue="1"/> 763 </axis-subsets> 764 </variable-font> 765 766 767``<axis-subsets>`` element 768-------------------------- 769 770- Child of ``<variable-font>`` 771- Defines the portion of the design space that this variable font covers. 772- Each axis that you want to include in the VF needs to be mentioned here. 773- Not mentioning an axis is equivalent to slicing the space at the default 774 value of that axis. 775 776.. versionadded:: 5.0 777 778 779``<axis-subset>`` element 780......................... 781 782- Child of ``<axis-subsets>`` 783- Defines the subset of one axis, by ``name=""``, that the variable font covers. 784- If this axis is continuous, the VF can either cover: 785 786 1. the whole axis 787 788 .. code:: xml 789 790 <axis-subset name="Weight"/> 791 792 2. a sub-range of the full axis 793 794 .. code:: xml 795 796 <axis-subset name="Weight" userminimum="400" usermaximum="500" userdefault="400"/> 797 798 3. a specific value along that axis; then the axis is not functional in the VF 799 but the design space is sliced at the given location. *Note:* While valid to have a 800 specific value that doesn’t have a matching ``<source>`` at that value, currently there 801 isn’t an implentation that supports this. See `this fontmake issue 802 <https://github.com/googlefonts/fontmake/issues/920>`_. 803 804 .. code:: xml 805 806 <!-- Make a bold VF --> 807 <axis-subset name="Weight" uservalue="700"/> 808 809- If this axis is discrete, then only the third option above is possible: 810 give one value along the axis. 811 812 .. code:: xml 813 814 <!-- Make an italic VF --> 815 <axis-subset name="Italic" uservalue="1"/> 816 817 818.. versionadded:: 5.0 819 820.. rubric:: Attributes 821 822- ``name``: required, string. Name of the axis to subset. 823 824When defining a range: 825 826- ``userminimum``: optional, number. 827 Lower end of the range, in user coordinates. 828 If not mentioned, assume the axis's minimum. 829- ``usermaximum``: optional, number. 830 Upper end of the range, in user coordinates. 831 If not mentioned, assume the axis's maximum. 832- ``userdefault``: optional, number. 833 New default value of subset axis, in user coordinates. 834 If not mentioned, assume the axis's default. 835 If the axis's default falls outside of the subset range, then the new default 836 will be the extremum that is closest to the full axis's default. 837 838When defining a single value: 839 840- ``uservalue``: required, number. 841 Single value, in user coordinates, at which to snapshot the design space 842 while building this VF. 843 844 845``<lib>`` element (variable font) 846--------------------------------- 847 848Arbitrary data about this variable font. 849 850.. versionadded:: 5.0 851 852.. seealso:: :ref:`lib` 853 854Here is an example of using the ``public.fontInfo`` lib key to gain more granular 855control over the font info of a variable font, in this case setting some names to 856reflect the fact that this is a Narrow variable font subset from the larger designspace. 857This lib key allows font info in variable fonts to be more specific than the font 858info of the sources. 859 860.. rubric:: Example 861 862.. code:: xml 863 864 <variable-font name="MyFontNarrVF"> 865 <axis-subsets> 866 <axis-subset name="Weight"/> 867 <axis-subset name="Width" uservalue="75"/> 868 </axis-subsets> 869 <lib> 870 <dict> 871 <key>public.fontInfo</key> 872 <dict> 873 <key>familyName</key> 874 <string>My Font Narrow VF</string> 875 <key>styleName</key> 876 <string>Regular</string> 877 <key>postscriptFontName</key> 878 <string>MyFontNarrVF-Regular</string> 879 <key>trademark</key> 880 <string>My Font Narrow VF is a registered trademark...</string> 881 </dict> 882 </dict> 883 </lib> 884 </variable-font> 885 886 887Instances included in the variable font 888--------------------------------------- 889 890.. figure:: v5_variable_fonts_vs_instances.png 891 :width: 650px 892 :alt: A designspace version 5 lists many instances and variable fonts. Each 893 variable font gets in its fvar table whichever instances fall within 894 the bounds of the variable font's subset axes. 895 896 Illustration of instances included in a variable font. 897 898 899======================= 900``<instances>`` element 901======================= 902 903The ``<instances>`` element contains one or more ``<instance>`` elements. 904 905 906``<instance>`` element 907====================== 908 909- Defines a single font that can be calculated with the designspace. 910- Child element of ``<instances>`` 911- For use in varLib the instance element really only needs the names 912 and the location. The ``<glyphs>`` element is not required. 913- MutatorMath uses the ``<glyphs>`` element to describe how certain 914 glyphs need different masters, mainly to describe the effects of 915 conditional rules in Superpolator. 916- Location in designspace coordinates. 917 918 919.. rubric:: Attributes 920 921- ``familyname``: required, string. The family name of the instance 922 font. Corresponds with ``font.info.familyName`` 923- ``stylename``: required, string. The style name of the instance font. 924 Corresponds with ``font.info.styleName`` 925- ``name``: required, string. A unique name that can be used to 926 identify this font if it needs to be referenced elsewhere. 927- ``filename``: string. Required for MutatorMath. A path to the 928 instance file, relative to the root path of this document. The path 929 can be at the same level as the document or lower. 930- ``postscriptfontname``: string. Optional for MutatorMath. Corresponds 931 with ``font.info.postscriptFontName`` 932- ``stylemapfamilyname``: string. Optional for MutatorMath. Corresponds 933 with ``styleMapFamilyName`` 934- ``stylemapstylename``: string. Optional for MutatorMath. Corresponds 935 with ``styleMapStyleName`` 936- ``location``: string. Optional. Describes the location of this instance, 937 taking it from the root level ``<labels>`` (STAT format 4) element with the 938 same name as the string. 939 940 .. versionadded:: 5.0 941 942 943``<location>`` element (instance) 944--------------------------------- 945 946Defines the coordinates of this instance in the design space. 947 948.. seealso:: :ref:`Full documentation of the \<location\> element <location>` 949 950 951``<dimension>`` element (instance) 952.................................. 953 954.. seealso:: :ref:`Full documentation of the \<dimension\> element <dimension>` 955 956 957``<lib>`` element (instance) 958---------------------------- 959 960Arbitrary data about this instance. 961 962.. seealso:: :ref:`lib` 963 964 965``<stylename>``, ``<familyname>``, ``<stylemapstylename>``, ``<stylemapfamilyname>`` elements: localised names for instances 966---------------------------------------------------------------------------------------------------------------------------- 967 968Localised names for instances can be included with these simple elements 969with an ``xml:lang`` attribute: 970`XML language definition <https://www.w3.org/International/questions/qa-when-xmllang.en>`__ 971 972- ``<stylename>`` 973- ``<familyname>`` 974- ``<stylemapstylename>`` 975- ``<stylemapfamilyname>`` 976 977 978.. rubric:: Example 979 980.. code:: xml 981 982 <stylename xml:lang="fr">Demigras</stylename> 983 <stylename xml:lang="ja">半ば</stylename> 984 <familyname xml:lang="fr">Montserrat</familyname> 985 <familyname xml:lang="ja">モンセラート</familyname> 986 <stylemapstylename xml:lang="de">Standard</stylemapstylename> 987 <stylemapfamilyname xml:lang="de">Montserrat Halbfett</stylemapfamilyname> 988 <stylemapfamilyname xml:lang="ja">モンセラート SemiBold</stylemapfamilyname> 989 990 991Example for varLib 992------------------ 993 994.. code:: xml 995 996 <instance familyname="InstanceFamilyName" filename="instances/instanceTest2.ufo" name="instance.ufo2" postscriptfontname="InstancePostscriptName" stylemapfamilyname="InstanceStyleMapFamilyName" stylemapstylename="InstanceStyleMapStyleName" stylename="InstanceStyleName"> 997 <location> 998 <dimension name="width" xvalue="400" yvalue="300" /> 999 <dimension name="weight" xvalue="66" /> 1000 </location> 1001 <lib> 1002 <dict> 1003 <key>com.coolDesignspaceApp.specimenText</key> 1004 <string>Hamburgerwhatever</string> 1005 </dict> 1006 </lib> 1007 </instance> 1008 1009 1010Here is an example using STAT format 4 labels to define the location of the 1011instance directly. 1012 1013.. code:: xml 1014 1015 <?xml version='1.0' encoding='utf-8'?> 1016 <designspace format="5.0"> 1017 <!-- ... --> 1018 <labels> 1019 <!-- define STAT format 4 labels here --> 1020 <!-- New in version 5.0 --> 1021 <label name="Extra Light"> 1022 <location> 1023 <dimension name="weight" uservalue="123" /> 1024 </location> 1025 </label> 1026 </labels> 1027 <!-- ... --> 1028 <instances> 1029 <instance filename="instances/labelled.ufo" location="Extra Light" /> 1030 </instances> 1031 </designspace> 1032 1033Here is an example of using the ``public.fontInfo`` lib key to gain more granular 1034control over the font info of the instances. 1035 1036``openTypeNameWWSFamilyName`` and ``openTypeNameWWSSubfamilyName`` are not able to 1037be set by attributes on the ``<instance>`` element. The ``openTypeOS2WeightClass`` 1038key is superseding the value that would have been set by the ``weight`` axis value. 1039The ``trademark`` key is superseding the value that would have been set by UFO source 1040at the origin. If the designer wishes to set name records for other encodings, 1041platforms or laguages, they should do so using the ``openTypeNameRecords`` key, like 1042they would in a UFO source. 1043 1044See `UFO3 fontinfo.plist specification <https://unifiedfontobject.org/versions/ufo3/fontinfo.plist/>`_. 1045 1046.. code:: xml 1047 1048 <instance familyname="My Font" stylename="Text Light" filename="instances/MyFont-TextLight.ufo" postscriptfontname="MyFont-TextLight" stylemapfamilyname="My Font Text Light" stylemapstylename="regular"> 1049 <location> 1050 <dimension name="optical" xvalue="6"/> 1051 <dimension name="weight" xvalue="325"/> 1052 </location> 1053 <lib> 1054 <dict> 1055 <key>public.fontInfo</key> 1056 <dict> 1057 <key>openTypeNameWWSFamilyName</key> 1058 <string>My Font Text</string> 1059 <key>openTypeNameWWSSubfamilyName</key> 1060 <string>Light</string> 1061 <key>openTypeOS2WeightClass</key> 1062 <integer>300</integer> 1063 <key>trademark</key> 1064 <string>My Font Text Light is a registered trademark...</string> 1065 <key>openTypeNameRecords</key> 1066 <array> 1067 <dict> 1068 <key>encodingID</key> 1069 <integer>1</integer> 1070 <key>languageID</key> 1071 <integer>1031</integer> 1072 <key>nameID</key> 1073 <integer>7</integer> 1074 <key>platformID</key> 1075 <integer>3</integer> 1076 <key>string</key> 1077 <string>Meine Schrift Text Leicht ist eine registrierte Marke...</string> 1078 </dict> 1079 </array> 1080 </dict> 1081 </dict> 1082 </lib> 1083 </instance> 1084 1085``<glyphs>`` element (instance) 1086------------------------------- 1087 1088- Container for ``<glyph>`` elements. 1089- Optional 1090- MutatorMath only. 1091 1092.. deprecated:: 5.0 1093 1094 1095``<glyph>`` element (instance) 1096.............................. 1097 1098- Child element of ``<glyphs>`` 1099- May contain a ``<location>`` element. 1100 1101.. deprecated:: 5.0 1102 1103.. rubric:: Attributes 1104 1105- ``name``: string. The name of the glyph. 1106- ``unicode``: string. Unicode values for this glyph, in hexadecimal. 1107 Multiple values should be separated with a space. 1108- ``mute``: optional attribute, number 1 or 0. Indicate if this glyph 1109 should be supressed in the output. 1110 1111 1112``<note>`` element 1113,,,,,,,,,,,,,,,,,, 1114 1115- String. The value corresponds to glyph.note in UFO. 1116 1117.. deprecated:: 5.0 1118 1119 1120``<masters>`` element 1121,,,,,,,,,,,,,,,,,,,,, 1122 1123- Container for ``<master>`` elements 1124- These ``<master>`` elements define an alternative set of glyph masters 1125 for this glyph. 1126 1127.. deprecated:: 5.0 1128 1129 1130``<master>`` element 1131++++++++++++++++++++ 1132 1133- Defines a single alternative master for this glyph. 1134 1135.. deprecated:: 5.0 1136 1137.. rubric:: Attributes 1138 1139- ``glyphname``: the name of the alternate master glyph. 1140- ``source``: the identifier name of the source this master glyph needs 1141 to be loaded from 1142 1143 1144Example for MutatorMath 1145....................... 1146 1147.. code:: xml 1148 1149 <instance familyname="InstanceFamilyName" filename="instances/instanceTest2.ufo" name="instance.ufo2" postscriptfontname="InstancePostscriptName" stylemapfamilyname="InstanceStyleMapFamilyName" stylemapstylename="InstanceStyleMapStyleName" stylename="InstanceStyleName"> 1150 <location> 1151 <dimension name="width" xvalue="400" yvalue="300" /> 1152 <dimension name="weight" xvalue="66" /> 1153 </location> 1154 <glyphs> 1155 <glyph name="arrow2" /> 1156 <glyph name="arrow" unicode="0x4d2 0x4d3"> 1157 <location> 1158 <dimension name="width" xvalue="100" /> 1159 <dimension name="weight" xvalue="120" /> 1160 </location> 1161 <note>A note about this glyph</note> 1162 <masters> 1163 <master glyphname="BB" source="master.ufo1"> 1164 <location> 1165 <dimension name="width" xvalue="20" /> 1166 <dimension name="weight" xvalue="20" /> 1167 </location> 1168 </master> 1169 </masters> 1170 </glyph> 1171 </glyphs> 1172 <kerning /> 1173 <info /> 1174 <lib> 1175 <dict> 1176 <key>com.coolDesignspaceApp.specimenText</key> 1177 <string>Hamburgerwhatever</string> 1178 </dict> 1179 </lib> 1180 </instance> 1181 1182 1183.. _lib: 1184 1185============================= 1186``<lib>`` element (top-level) 1187============================= 1188 1189The ``<lib>`` element contains arbitrary data. 1190 1191- Child element of ``<designspace>``, ``<variable-font>`` and ``<instance>`` 1192- If present, content must be an XML Property List (plist). 1193 <https://en.wikipedia.org/wiki/Property_list>__ 1194- Contains arbitrary data about the whole document or about a specific 1195 variable font or instance. 1196- Items in the dict need to use **reverse domain name notation** 1197 <https://en.wikipedia.org/wiki/Reverse_domain_name_notation>__ 1198 1199.. rubric:: Example: 1200 1201.. code:: xml 1202 1203 <lib> 1204 <dict> 1205 <key>com.company.fontEditor.myString</key> 1206 <string>The contents use the PLIST format.</string> 1207 </dict> 1208 </lib> 1209 1210 1211
