diff options
Diffstat (limited to 'Doc/source/designspaceLib/xml.rst')
| -rw-r--r-- | Doc/source/designspaceLib/xml.rst | 125 |
1 files changed, 113 insertions, 12 deletions
diff --git a/Doc/source/designspaceLib/xml.rst b/Doc/source/designspaceLib/xml.rst index 6267b025..4e3492ef 100644 --- a/Doc/source/designspaceLib/xml.rst +++ b/Doc/source/designspaceLib/xml.rst @@ -20,10 +20,15 @@ Overview .. code:: xml <?xml version='1.0' encoding='utf-8'?> - <designspace format="5.0"> + <designspace format="5.1"> <axes> <!-- define axes here --> <axis... /> + <mappings> + <!-- define axis mappings here --> + <!-- New in version 5.1 --> + <mapping... /> + </mappings> </axes> <labels> <!-- define STAT format 4 labels here --> @@ -162,10 +167,17 @@ For a discrete axis: ``<labels>`` element (axis) --------------------------- -The ``<labels>`` element contains one or more ``<label>`` elements. +The ``<labels>`` element contains one or more ``<label>`` elements, and can +indicate this axis' STAT ordering. .. versionadded:: 5.0 +.. rubric:: Attributes + +- ``ordering``: optional, int, default: natural position of this axis in the list + of axes. STAT table field ``axisOrdering`` for this axis. + + See: `OTSpec STAT Axis Record <https://docs.microsoft.com/en-us/typography/opentype/spec/stat#axis-records>`_ ``<label>`` element (axis) .......................... @@ -248,6 +260,64 @@ Example of all axis elements together </axes> +``<mappings>`` element +====================== + +- Define axis mappings. +- Child element of ``axes`` + + + .. versionadded:: 5.1 + + +``<mapping>`` element +--------------------- + +- Defines an axis mapping. +- Child element of ``<mappings>`` + + + .. versionadded:: 5.1 + + +``<input>`` element +................... + +- Defines the input location of an axis mapping. +- Child element of ``<mapping>`` +- Contains one or more ``<dimension>`` elements with designspace locations. + + .. versionadded:: 5.1 + + +``<output>`` element +................... + +- Defines the output location of an axis mapping. +- Child element of ``<mapping>`` +- Contains one or more ``<dimension>`` elements with designspace locations. + + .. versionadded:: 5.1 + + +Example of all mappings elements together +========================================= + +.. code:: xml + + <mappings> + <mapping> + <input> + <dimension name="weight" xvalue="900"/> + <dimension name="width" xvalue="150"/> + </input> + <output> + <dimension name="weight" xvalue="870"/> + </output> + </mapping> + </mappings> + + ================================ ``<labels>`` element (top-level) ================================ @@ -297,7 +367,7 @@ See: `OTSpec STAT Axis value table, format 4 <https://docs.microsoft.com/en-us/t ``<dimension>`` element ....................... -- Child element of ``<location>`` +- Child element of ``<location>``, ``input``, or ``output`` elements .. rubric:: Attributes @@ -387,7 +457,7 @@ glyphname pairs: the glyphs that need to be substituted. For a rule to be trigge - Defines a named rule. - Each ``<rule>`` element contains one or more ``<conditionset>`` elements. -- **Only one** ``<conditionset>`` needs to be true to trigger the rule (logical OR). +- **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. - **All** conditions in a ``<conditionset>`` must be true to make the ``<conditionset>`` true. (logical AND) - 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. - A rule element needs to contain one or more ``<sub>`` elements in order to be compiled to a variable font. @@ -405,7 +475,7 @@ glyphname pairs: the glyphs that need to be substituted. For a rule to be trigge -------------------------- - Child element of ``<rule>`` -- Contains one or more ``<condition>`` elements. +- Contains zero or more ``<condition>`` elements. ``<condition>`` element @@ -504,7 +574,7 @@ The ``<sources>`` element contains one or more ``<source>`` elements. While this could be extracted from the font data itself, it can be more efficient to add it here. - ``stylename``: optional, string. The style name of the source font. -- ``name``: required, string. A unique name that can be used to +- ``name``: optional, string. A unique name that can be used to identify this font if it needs to be referenced elsewhere. - ``filename``: required, string. A path to the source file, relative to the root path of this document. The path can be at the same level @@ -535,13 +605,13 @@ element with an ``xml:lang`` attribute: Defines the coordinates of this source in the design space. -.. seealso:: `Full documentation of the <location> element <location>`__ +.. seealso:: :ref:`Full documentation of the \<location\> element <location>` ``<dimension>`` element (source) ................................ -.. seealso:: `Full documentation of the <dimension> element <dimension>`__ +.. seealso:: :ref:`Full documentation of the \<dimension\> element <dimension>` ``<lib>`` element (source) @@ -797,7 +867,7 @@ The ``<instances>`` element contains one or more ``<instance>`` elements. - Defines a single font that can be calculated with the designspace. - Child element of ``<instances>`` -- For use in Varlib the instance element really only needs the names +- For use in varLib the instance element really only needs the names and the location. The ``<glyphs>`` element is not required. - MutatorMath uses the ``<glyphs>`` element to describe how certain glyphs need different masters, mainly to describe the effects of @@ -822,6 +892,11 @@ The ``<instances>`` element contains one or more ``<instance>`` elements. with ``styleMapFamilyName`` - ``stylemapstylename``: string. Optional for MutatorMath. Corresponds with ``styleMapStyleName`` +- ``location``: string. Optional. Describes the location of this instance, + taking it from the root level ``<labels>`` (STAT format 4) element with the + same name as the string. + + .. versionadded:: 5.0 ``<location>`` element (instance) @@ -829,13 +904,13 @@ The ``<instances>`` element contains one or more ``<instance>`` elements. Defines the coordinates of this instance in the design space. -.. seealso:: `Full documentation of the <location> element <location>`__ +.. seealso:: :ref:`Full documentation of the \<location\> element <location>` ``<dimension>`` element (instance) .................................. -.. seealso:: `Full documentation of the <dimension> element <dimension>`__ +.. seealso:: :ref:`Full documentation of the \<dimension\> element <dimension>` ``<lib>`` element (instance) @@ -872,7 +947,7 @@ with an ``xml:lang`` attribute: <stylemapfamilyname xml:lang="ja">モンセラート SemiBold</stylemapfamilyname> -Example for varlib +Example for varLib ------------------ .. code:: xml @@ -891,6 +966,30 @@ Example for varlib </instance> +Here is an example using STAT format 4 labels to define the location of the +instance directly. + +.. code:: xml + + <?xml version='1.0' encoding='utf-8'?> + <designspace format="5.0"> + <!-- ... --> + <labels> + <!-- define STAT format 4 labels here --> + <!-- New in version 5.0 --> + <label name="Extra Light"> + <location> + <dimension name="weight" uservalue="123" /> + </location> + </label> + </labels> + <!-- ... --> + <instances> + <instance filename="instances/labelled.ufo" location="Extra Light" /> + </instances> + </designspace> + + ``<glyphs>`` element (instance) ------------------------------- @@ -998,6 +1097,8 @@ Example for MutatorMath The ``<lib>`` element contains arbitrary data. - Child element of ``<designspace>``, ``<variable-font>`` and ``<instance>`` +- If present, content must be an XML Property List (plist). + <https://en.wikipedia.org/wiki/Property_list>__ - Contains arbitrary data about the whole document or about a specific variable font or instance. - Items in the dict need to use **reverse domain name notation** |