From 4670087c1acab4b2e2618d9a2fdf0c47bb04203e Mon Sep 17 00:00:00 2001
From: Gavin <gavin@hibernate.org>
Date: Mon, 2 Jan 2023 22:26:31 +0100
Subject: [PATCH] mention XML mappings in overview

---
 hibernate-core/src/main/javadoc/overview.html | 21 +++++++++++++++++++
 release/src/release/javadoc/overview.html     | 21 +++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/hibernate-core/src/main/javadoc/overview.html b/hibernate-core/src/main/javadoc/overview.html
index d69e3dcca4..f50b638e7b 100644
--- a/hibernate-core/src/main/javadoc/overview.html
+++ b/hibernate-core/src/main/javadoc/overview.html
@@ -75,6 +75,27 @@
     The full power of Hibernate can only be unlocked via judicious use of these extra annotations.
 </p>
 
+<h3>XML-based mappings</h3>
+
+Annotation-based mappings are the best choice for most users, but Hibernate offers XML-based
+mappings as an alternative.
+
+<ul>
+    <li>
+        The JPA-standard XML schema is
+        <a href="https://jakarta.ee/xml/ns/persistence/orm/orm_3_0.xsd">orm_3_0.xsd</a>.
+    </li>
+    <li>
+        Hibernate extends this schema with some additional mapping elements. The schema is
+        <a href="https://hibernate.org/xsd/orm/mapping/mapping-3.1.0.xsd">mapping-3.1.0.xsd</a>.
+    </li>
+    <li>
+        Prior to the existence of JPA, Hibernate had its own format for XML-based mappings,
+        which still works, though it has not been improved in a long time. The DTD is
+        <a href="http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">hibernate-mapping-3.0.dtd</a>
+    </li>
+</ul>
+
 <h3>Bootstrapping Hibernate</h3>
 
 <p>
diff --git a/release/src/release/javadoc/overview.html b/release/src/release/javadoc/overview.html
index d69e3dcca4..86e1e8202b 100644
--- a/release/src/release/javadoc/overview.html
+++ b/release/src/release/javadoc/overview.html
@@ -75,6 +75,27 @@
     The full power of Hibernate can only be unlocked via judicious use of these extra annotations.
 </p>
 
+<h3>XML-based mappings</h3>
+
+Annotation-based mappings are the best choice for most users, but Hibernate offers XML-based
+mappings as an alternative.
+
+<ul>
+    <li>
+        The JPA-standard XML schema is
+        <a href="https://jakarta.ee/xml/ns/persistence/orm/orm_3_0.xsd">orm_3_0.xsd</a>.
+    </li>
+    <li>
+        Hibernate extends this schema with some additional mapping elements. The schema is
+        <a href="https://hibernate.org/xsd/orm/mapping/mapping-3.1.0.xsd">mapping-3.1.0.xsd</a>.
+    </li>
+    <li>
+        Prior to the existence of JPA, Hibernate had its own format for XML-based mappings,
+        which still works, though it has not been improved in a long time. The DTD is
+        <a href="https://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">hibernate-mapping-3.0.dtd</a>
+    </li>
+</ul>
+
 <h3>Bootstrapping Hibernate</h3>
 
 <p>