From 17d0f1cad73e21b1ba20c399bf35d809c8625ebe Mon Sep 17 00:00:00 2001
From: Panos Vagenas <pva@zurich.ibm.com>
Date: Mon, 21 Sep 2026 14:32:16 +0200
Subject: [PATCH] allow multiple captions

Signed-off-by: Panos Vagenas <pva@zurich.ibm.com>
---
 doclang/doclang.xsd                           |  4 ++--
 spec.md                                       |  4 ++--
 .../nok_caption_after_description.dclg        | 12 ++++++++++
 tests/data/valid/ok_caption_multiple.dclg     | 22 +++++++++++++++++++
 4 files changed, 38 insertions(+), 4 deletions(-)
 create mode 100644 tests/data/invalid/nok_caption_after_description.dclg
 create mode 100644 tests/data/valid/ok_caption_multiple.dclg

diff --git a/doclang/doclang.xsd b/doclang/doclang.xsd
index a04e3c7..e3bd6be 100644
--- a/doclang/doclang.xsd
+++ b/doclang/doclang.xsd
@@ -218,7 +218,7 @@
   </xs:element>
 
   <!-- ============================================ -->
-  <!-- ELEMENT HEAD (element_head): optional label, thread, xref or href, layer, location_block, caption, description, summary, custom -->
+  <!-- ELEMENT HEAD (element_head): optional label, thread, xref or href, layer, location_block, zero or more captions, description, summary, custom -->
   <!-- ============================================ -->
 
   <xs:group name="element_head">
@@ -231,7 +231,7 @@
       </xs:choice>
       <xs:element ref="dl:layer" minOccurs="0"/>
       <xs:group ref="dl:location_block" minOccurs="0"/>
-      <xs:element ref="dl:caption" minOccurs="0"/>
+      <xs:element ref="dl:caption" minOccurs="0" maxOccurs="unbounded"/>
       <xs:element ref="dl:description" minOccurs="0"/>
       <xs:element ref="dl:summary" minOccurs="0"/>
       <xs:element ref="dl:custom" minOccurs="0"/>
diff --git a/spec.md b/spec.md
index 5f23677..9d1f2bb 100644
--- a/spec.md
+++ b/spec.md
@@ -152,7 +152,7 @@ The XML content of a semantic element begins with an *element head*, which is a
 - [`<xref>`](#xref) or [`<href>`](#href) (mutually exclusive, optional)
 - [`<layer>`](#layer) (optional)
 - optional sequence of 4 [`<location>`](#location)s, whereby values are interpreted in alternating axis order, as `x_min, y_min, x_max, y_max` (after resolution normalization), w.r.t. the top-left corner of the page
-- [`<caption>`](#caption) (optional)
+- [`<caption>`](#caption) (optional, may be repeated)
 - [`<description>`](#description) (optional)
 - [`<summary>`](#summary) (optional)
 - [`<custom>`](#custom) (optional)
@@ -2573,7 +2573,7 @@ None
 
 ##### `<caption>`
 
-Optional part of the element head for capturing an associated caption. Unlike [`<description>`](#description) or [`<summary>`](#summary), [`<caption>`](#caption) is an actual document component, which can have its own location information etc. For example, a caption shown underneath a chart.
+Optional part of the element head for capturing an associated caption. Unlike [`<description>`](#description) or [`<summary>`](#summary), [`<caption>`](#caption) is an actual document component, which can have its own location information etc. For example, a caption shown underneath a chart. An element head may contain multiple captions, e.g. a figure with both a title above and a note below, or the same caption in several languages.
 
 ###### Allowed Context
 
diff --git a/tests/data/invalid/nok_caption_after_description.dclg b/tests/data/invalid/nok_caption_after_description.dclg
new file mode 100644
index 0000000..7b42532
--- /dev/null
+++ b/tests/data/invalid/nok_caption_after_description.dclg
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<doclang xmlns="https://www.doclang.ai/ns/v0">
+
+  <!-- all captions must precede description in the element head -->
+  <picture>
+    <caption>FIG. 1. First caption</caption>
+    <description>Derived description of the figure.</description>
+    <caption>FIG. 1. Second caption</caption>
+    <src uri="fig1.png"/>
+  </picture>
+
+</doclang>
diff --git a/tests/data/valid/ok_caption_multiple.dclg b/tests/data/valid/ok_caption_multiple.dclg
new file mode 100644
index 0000000..7901647
--- /dev/null
+++ b/tests/data/valid/ok_caption_multiple.dclg
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<doclang xmlns="https://www.doclang.ai/ns/v0">
+
+  <!-- multiple captions in the element head, followed by description and summary -->
+  <picture>
+    <caption>FIG. 1. System architecture</caption>
+    <caption>Source: internal design review</caption>
+    <description>Block diagram of the system.</description>
+    <summary>Shows the main components.</summary>
+    <src uri="fig1.png"/>
+  </picture>
+
+  <!-- multiple captions on a table, after location -->
+  <table>
+    <location value="40"/><location value="130"/>
+    <location value="440"/><location value="300"/>
+    <caption>Table 1: Results</caption>
+    <caption>Table 1 (cont.)</caption>
+    <fcel/>Value<nl/>
+  </table>
+
+</doclang>