From 68387f9bdc82a56bf56945da3883a993bc40e2a5 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <dgustafsson@postgresql.org>
Date: Tue, 23 Jan 2024 13:20:15 +0100
Subject: [PATCH] doc: Add acronym and glossary term for Access Method

AM was used throughout the documentation to denote Access Method, but
the acronym was not described.  This adds an acronym entry as well as
a glossary term which the acronym links to.  Each page which describe
AMs have the first occurrence with <acronym> markup.

Reported-by: alaa.attya91@gmail.com
Reviewed-by: Alvaro Herrera <alvherre@alvh.no-ip.org>
Discussion: https://postgr.es/m/169974408805.398198.6927340566912872957@wrigleys.postgresql.org
---
 doc/src/sgml/acronyms.sgml |  9 +++++++++
 doc/src/sgml/btree.sgml    |  2 +-
 doc/src/sgml/glossary.sgml | 15 +++++++++++++++
 doc/src/sgml/indexam.sgml  |  2 +-
 doc/src/sgml/tableam.sgml  |  2 +-
 5 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index 22e0dc5c70..817d062c7e 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -9,6 +9,15 @@
 
   <variablelist>
 
+   <varlistentry>
+    <term><acronym>AM</acronym></term>
+    <listitem>
+     <para>
+      <link linkend="glossary-am">Access Method</link>
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><acronym>ANSI</acronym></term>
     <listitem>
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index 6f608a14bf..be8210286b 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -27,7 +27,7 @@
   and understanding of sorting semantics.  Therefore, they've acquired
   some features that go beyond what would be needed just to support btree
   indexes, and parts of the system that are quite distant from the
-  btree AM make use of them.
+  btree <acronym>AM</acronym> make use of them.
  </para>
 
 </sect1>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index ccd480aede..8c2f11480d 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -39,6 +39,21 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-am">
+   <glossterm>Access Method</glossterm>
+   <glossdef>
+    <para>
+     Interfaces which <productname>PostgreSQL</productname> use in order to
+     access data in tables and indexes.  This abstraction allows for adding
+     support for new types of data storage.
+    </para>
+    <para>
+     For more information, see <xref linkend="tableam" /> and
+     <xref linkend="indexam" />.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry>
    <glossterm>Analytic function</glossterm>
    <glosssee otherterm="glossary-window-function" />
diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index cc4135e394..b68daa55ae 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -215,7 +215,7 @@ typedef struct IndexAmRoutine
    the first; however they are permitted to require some restriction to
    appear for the first index column, and this is signaled by setting
    <structfield>amoptionalkey</structfield> false.
-   One reason that an index AM might set
+   One reason that an index <acronym>AM</acronym> might set
    <structfield>amoptionalkey</structfield> false is if it doesn't index
    null values.  Since most indexable operators are
    strict and hence cannot return true for null inputs,
diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
index 6a6eb2b766..4b37f2e5a6 100644
--- a/doc/src/sgml/tableam.sgml
+++ b/doc/src/sgml/tableam.sgml
@@ -56,7 +56,7 @@
 
  <para>
   To implement an access method, an implementor will typically need to
-  implement an AM-specific type of tuple table slot (see
+  implement an <acronym>AM</acronym>-specific type of tuple table slot (see
   <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/executor/tuptable.h;hb=HEAD">
    <filename>src/include/executor/tuptable.h</filename></ulink>), which allows
    code outside the access method to hold references to tuples of the AM, and