allow multiple captions

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"/>

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
 

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>

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>