v2-0001-doc-Add-acronym-and-glossary-term-for-Access-Meth.patch

From a81e66cad5afdd250f2b904212dd78b51a65d164 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <dgustafsson@postgresql.org>
Date: Mon, 13 Nov 2023 13:19:48 +0100
Subject: [PATCH v2] 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.

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  | 10 +++++-----
 doc/src/sgml/tableam.sgml  |  6 +++---
 5 files changed, 33 insertions(+), 9 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 fe8def41d0..26b739b7ca 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="indexam" /> and
+      <xref linkend="tableam" />.
+    </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 30eda37afa..133d4180ea 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -212,7 +212,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,
@@ -330,7 +330,7 @@ aminsert (Relation indexRelation,
    new tuple is a logically unchanged successor MVCC tuple version.  This
    happens when an <command>UPDATE</command> takes place that does not
    modify any columns covered by the index, but nevertheless requires a
-   new version in the index.  The index AM may use this hint to decide
+   new version in the index.  The index <acronym>AM</acronym> may use this hint to decide
    to apply bottom-up index deletion in parts of the index where many
    versions of the same logical row accumulate.  Note that updating a non-key
    column or a column that only appears in a partial index predicate does not
@@ -355,7 +355,7 @@ aminsert (Relation indexRelation,
   </para>
 
   <para>
-   If the index AM wishes to cache data across successive index insertions
+   If the index <acronym>AM</acronym> wishes to cache data across successive index insertions
    within an SQL statement, it can allocate space
    in <literal>indexInfo-&gt;ii_Context</literal> and store a pointer to the
    data in <literal>indexInfo-&gt;ii_AmCache</literal> (which will be NULL
@@ -387,7 +387,7 @@ ambulkdelete (IndexVacuumInfo *info,
    <function>ambulkdelete</function> might need to be called more than once when many
    tuples are to be deleted.  The <literal>stats</literal> argument is the result
    of the previous call for this index (it is NULL for the first call within a
-   <command>VACUUM</command> operation).  This allows the AM to accumulate statistics
+   <command>VACUUM</command> operation).  This allows the <acronym>AM</acronym> to accumulate statistics
    across the whole operation.  Typically, <function>ambulkdelete</function> will
    modify and return the same struct if the passed <literal>stats</literal> is not
    null.
@@ -672,7 +672,7 @@ amgettuple (IndexScanDesc scan,
    If the index supports <link linkend="indexes-index-only-scans">index-only
    scans</link> (i.e., <function>amcanreturn</function> returns true for any
    of its columns),
-   then on success the AM must also check <literal>scan-&gt;xs_want_itup</literal>,
+   then on success the <acronym>AM</acronym> must also check <literal>scan-&gt;xs_want_itup</literal>,
    and if that is true it must return the originally indexed data for the
    index entry.  Columns for which <function>amcanreturn</function> returns
    false can be returned as nulls.
diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
index 6a6eb2b766..954663d29b 100644
--- a/doc/src/sgml/tableam.sgml
+++ b/doc/src/sgml/tableam.sgml
@@ -64,7 +64,7 @@
  </para>
 
  <para>
-  Currently, the way an AM actually stores data is fairly unconstrained. For
+  Currently, the way an <acronym>AM</acronym> actually stores data is fairly unconstrained. For
   example, it's possible, but not required, to use postgres' shared buffer
   cache.  In case it is used, it likely makes sense to use
   <productname>PostgreSQL</productname>'s standard page layout as described in
@@ -73,7 +73,7 @@
 
  <para>
   One fairly large constraint of the table access method API is that,
-  currently, if the AM wants to support modifications and/or indexes, it is
+  currently, if the <acronym>AM</acronym> wants to support modifications and/or indexes, it is
   necessary for each tuple to have a tuple identifier (<acronym>TID</acronym>)
   consisting of a block number and an item number (see also <xref
   linkend="storage-page-layout"/>).  It is not strictly necessary that the
@@ -83,7 +83,7 @@
  </para>
 
  <para>
-  For crash safety, an AM can use postgres' <link
+  For crash safety, an <acronym>AM</acronym> can use postgres' <link
   linkend="wal"><acronym>WAL</acronym></link>, or a custom implementation.
   If <acronym>WAL</acronym> is chosen, either <link
   linkend="generic-wal">Generic WAL Records</link> can be used,
-- 
2.32.1 (Apple Git-133)