[designspace] Add avar2 mapping support

Doc/source/designspaceLib/index.rst

@@ -127,20 +127,20 @@ Implementation and differences
 The designspace format has gone through considerable development.
 
  -  the format was originally written for MutatorMath.
- -  the format is now also used in fontTools.varlib.
+ -  the format is now also used in fontTools.varLib.
  -  not all values are be required by all implementations.
 
-Varlib vs. MutatorMath
+varLib vs. MutatorMath
 ----------------------
 
-There are some differences between the way MutatorMath and fontTools.varlib handle designspaces.
+There are some differences between the way MutatorMath and fontTools.varLib handle designspaces.
 
- -  Varlib does not support anisotropic interpolations.
+ -  varLib does not support anisotropic interpolations.
  -  MutatorMath will extrapolate over the boundaries of
-    the axes. Varlib can not (at the moment).
- -  Varlib requires much less data to define an instance than
+    the axes. varLib can not (at the moment).
+ -  varLib requires much less data to define an instance than
     MutatorMath.
- -  The goals of Varlib and MutatorMath are different, so not all
+ -  The goals of varLib and MutatorMath are different, so not all
     attributes are always needed.
 
 
@@ -174,6 +174,14 @@ it can become complex very quickly. So proceed with caution.
 Version history
 ===============
 
+Version 5.1
+-----------
+
+The format was extended to support arbitrary mapping between input and output
+designspace locations. The ``<axes>`` elements now can have a ``<mappings>``
+element that specifies such mappings, which when present carries data that is
+used to compile to an ``avar`` version 2 table.
+
 Version 5.0
 -----------
 

Doc/source/designspaceLib/scripting.rst

@@ -234,7 +234,7 @@ You can generate the UFOs with MutatorMath:
 
 -  Assuming the outline data in the masters is compatible.
 
-Or you can use the file in making a **variable font** with varlib.
+Or you can use the file in making a **variable font** with varLib.
 
 
 .. _working_with_v5:

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 -->
@@ -255,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)
 ================================
@@ -304,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
 
@@ -804,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
@@ -879,7 +942,7 @@ with an ``xml:lang`` attribute:
     <stylemapfamilyname xml:lang="ja">モンセラート SemiBold</stylemapfamilyname>
 
 
-Example for varlib
+Example for varLib
 ------------------
 
 .. code:: xml