From 896ac28f99c379ef8cf5b9d36cf3ba22230e237e Mon Sep 17 00:00:00 2001
From: Nikolaus Waxweiler <nikolaus.waxweiler@daltonmaag.com>
Date: Thu, 20 Jul 2023 15:18:36 +0100
Subject: [PATCH] Document instance labelling

---
 Doc/source/designspaceLib/xml.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/Doc/source/designspaceLib/xml.rst b/Doc/source/designspaceLib/xml.rst
index 05f884ecb..85ce8aa65 100644
--- a/Doc/source/designspaceLib/xml.rst
+++ b/Doc/source/designspaceLib/xml.rst
@@ -892,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)
@@ -961,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)
 -------------------------------