From 73bd40a2e84ceb72f139a132dd98265cbf603fbb Mon Sep 17 00:00:00 2001
From: Maria Scott <maria-12648430@hnc-agency.org>
Date: Wed, 3 May 2023 09:27:41 +0200
Subject: Move compatibility section to sets documentation

---
 lib/stdlib/doc/src/gb_sets.xml | 46 +++---------------------------
 lib/stdlib/doc/src/ordsets.xml |  5 ++++
 lib/stdlib/doc/src/sets.xml    | 65 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 42 deletions(-)

diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml
index 3477c2c90e..283c3f9198 100644
--- a/lib/stdlib/doc/src/gb_sets.xml
+++ b/lib/stdlib/doc/src/gb_sets.xml
@@ -68,48 +68,10 @@
 
   <section>
     <title>Compatibility</title>
-    <p>The following functions in this module also exist and provides
-      the same functionality in the
-      <seeerl marker="sets"><c>sets(3)</c></seeerl> and
-      <seeerl marker="ordsets"><c>ordsets(3)</c></seeerl>
-      modules. That is, by only changing the module name for each call,
-      you can try out different set representations.</p>
-    <list type="bulleted">
-      <item><seemfa marker="#add_element/2"><c>add_element/2</c></seemfa>
-      </item>
-      <item><seemfa marker="#del_element/2"><c>del_element/2</c></seemfa>
-      </item>
-      <item><seemfa marker="#filter/2"><c>filter/2</c></seemfa>
-      </item>
-      <item><seemfa marker="#fold/3"><c>fold/3</c></seemfa>
-      </item>
-      <item><seemfa marker="#from_list/1"><c>from_list/1</c></seemfa>
-      </item>
-      <item><seemfa marker="#intersection/1"><c>intersection/1</c></seemfa>
-      </item>
-      <item><seemfa marker="#intersection/2"><c>intersection/2</c></seemfa>
-      </item>
-      <item><seemfa marker="#is_element/2"><c>is_element/2</c></seemfa>
-      </item>
-      <item><seemfa marker="#is_empty/1"><c>is_empty/1</c></seemfa>
-      </item>
-      <item><seemfa marker="#is_set/1"><c>is_set/1</c></seemfa>
-      </item>
-      <item><seemfa marker="#is_subset/2"><c>is_subset/2</c></seemfa>
-      </item>
-      <item><seemfa marker="#new/0"><c>new/0</c></seemfa>
-      </item>
-      <item><seemfa marker="#size/1"><c>size/1</c></seemfa>
-      </item>
-      <item><seemfa marker="#subtract/2"><c>subtract/2</c></seemfa>
-      </item>
-      <item><seemfa marker="#to_list/1"><c>to_list/1</c></seemfa>
-      </item>
-      <item><seemfa marker="#union/1"><c>union/1</c></seemfa>
-      </item>
-      <item><seemfa marker="#union/2"><c>union/2</c></seemfa>
-      </item>
-    </list>
+    <p>See the <seeerl marker="sets#compatibility">Compatibility Section
+      in the <c>sets(3)</c> module</seeerl> for information about
+      the compatibility of the different implementations of sets in the
+      Standard Library.</p>
   </section>
 
   <datatypes>
diff --git a/lib/stdlib/doc/src/ordsets.xml b/lib/stdlib/doc/src/ordsets.xml
index 35127dcf95..7b02d13ab3 100644
--- a/lib/stdlib/doc/src/ordsets.xml
+++ b/lib/stdlib/doc/src/ordsets.xml
@@ -48,6 +48,11 @@
       that while <c>sets</c> considers two elements as different if they
       do not match (<c>=:=</c>), this module considers two elements as
       different if and only if they do not compare equal (<c>==</c>).</p>
+
+    <p>See the <seeerl marker="sets#compatibility">Compatibility Section
+      in the <c>sets(3)</c> module</seeerl> for more information about
+      the compatibility of the different implementations of sets in the
+      Standard Library.</p>
   </description>
 
   <datatypes>
diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml
index 53b64a3ac0..b3899c440f 100644
--- a/lib/stdlib/doc/src/sets.xml
+++ b/lib/stdlib/doc/src/sets.xml
@@ -69,6 +69,71 @@
 
   </description>
 
+  <section>
+    <title>Compatibility</title>
+    <p>The following functions in this module also exist and provide
+      the same functionality in the
+      <seeerl marker="gb_sets"><c>gb_sets(3)</c></seeerl> and
+      <seeerl marker="ordsets"><c>ordsets(3)</c></seeerl>
+      modules. That is, by only changing the module name for each call,
+      you can try out different set representations.</p>
+    <list type="bulleted">
+      <item><seemfa marker="#add_element/2"><c>add_element/2</c></seemfa>
+      </item>
+      <item><seemfa marker="#del_element/2"><c>del_element/2</c></seemfa>
+      </item>
+      <item><seemfa marker="#filter/2"><c>filter/2</c></seemfa>
+      </item>
+      <item><seemfa marker="#fold/3"><c>fold/3</c></seemfa>
+      </item>
+      <item><seemfa marker="#from_list/1"><c>from_list/1</c></seemfa>
+      </item>
+      <item><seemfa marker="#intersection/1"><c>intersection/1</c></seemfa>
+      </item>
+      <item><seemfa marker="#intersection/2"><c>intersection/2</c></seemfa>
+      </item>
+      <item><seemfa marker="#is_element/2"><c>is_element/2</c></seemfa>
+      </item>
+      <item><seemfa marker="#is_empty/1"><c>is_empty/1</c></seemfa>
+      </item>
+      <item><seemfa marker="#is_set/1"><c>is_set/1</c></seemfa>
+      </item>
+      <item><seemfa marker="#is_subset/2"><c>is_subset/2</c></seemfa>
+      </item>
+      <item><seemfa marker="#new/0"><c>new/0</c></seemfa>
+      </item>
+      <item><seemfa marker="#size/1"><c>size/1</c></seemfa>
+      </item>
+      <item><seemfa marker="#subtract/2"><c>subtract/2</c></seemfa>
+      </item>
+      <item><seemfa marker="#to_list/1"><c>to_list/1</c></seemfa>
+      </item>
+      <item><seemfa marker="#union/1"><c>union/1</c></seemfa>
+      </item>
+      <item><seemfa marker="#union/2"><c>union/2</c></seemfa>
+      </item>
+    </list>
+    <note>
+      <p>
+        While the three set implementations offer the same <em>functionality</em>
+        with respect to the aforementioned functions, their overall <em>behavior</em>
+        may differ. As mentioned, this module considers elements as different if
+        and only if they do not match (<c>=:=</c>), while both
+        <seeerl marker="ordsets"><c>ordsets</c></seeerl> and
+        <seeerl marker="gb_sets"><c>gb_sets</c></seeerl> consider elements as
+        different if and only if they do not compare equal (<c>==</c>).
+      </p>
+      <p><em>Example:</em></p>
+      <pre>
+1> <input>sets:is_element(1.0, sets:from_list([1])).</input>
+false
+2> <input>ordsets:is_element(1.0, ordsets:from_list([1])).</input>
+true
+2> <input>gb_sets:is_element(1.0, gb_sets:from_list([1])).</input>
+true</pre>
+    </note>
+  </section>
+
   <datatypes>
     <datatype>
       <name name="set" n_vars="1"/>
-- 
cgit v1.2.1