Horton

Thread

Commits

  1. doc: Add acronym and glossary term for Access Method

  1. add new acronym "AM"

    The Post Office <noreply@postgresql.org> — 2023-11-11T23:08:08Z

    The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/acronyms.html
Description:

while reading the progres codebase, i could find you're using the acronym
"AM" which denotes "Access Method". it's be nice to add it to the list of
acronyms

  2. Re: add new acronym "AM"

    Daniel Gustafsson <daniel@yesql.se> — 2023-11-13T11:00:20Z

    > On 12 Nov 2023, at 00:08, PG Doc comments form <noreply@postgresql.org> wrote:
> 
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/16/acronyms.html
> Description:
> 
> while reading the progres codebase, i could find you're using the acronym
> "AM" which denotes "Access Method". it's be nice to add it to the list of
> acronyms

That's a fair point.  It's sort of hard to refer back from the acronym list
though since we don't have a single Access Method section but instead one for
Indexes and one for Relations.  In the attached diff I propose that we add a
glossary entry for Access Method (suggested better wording much appreciated)
which the acronym can refer to.  Being such a core concept it doesn't seem like
a bad idea to explain it.

--
Daniel Gustafsson

  3. Re: add new acronym "AM"

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-11-13T11:20:15Z

    On 2023-Nov-13, Daniel Gustafsson wrote:

> That's a fair point.  It's sort of hard to refer back from the acronym list
> though since we don't have a single Access Method section but instead one for
> Indexes and one for Relations.  In the attached diff I propose that we add a
> glossary entry for Access Method (suggested better wording much appreciated)
> which the acronym can refer to.  Being such a core concept it doesn't seem like
> a bad idea to explain it.

+1 for a glossary entry.

+     Access methods are the interfaces which
+     <productname>PostgreSQL</productname> use in order to access relations
+     and indexes. This abstraction allows for adding support for new
+     types of tuple storage. For more information, see <xref linkend="indexam" />
+     and <xref linkend="tableam" />.

We don't start the glossary definition with the term we're defining.
For example, we say
  Atomicity
  The property of a transaction that ...
we don't say
  Atomicity
  Atomicity is the property of ...

So you would want your definition to be something like
"Interfaces which PostgreSQL use to ..."

I'd say "data in tables and indexes" rather than "relations and
indexes", and "data storage" instead of "tuple storage".

"For more information" should be its own <para>.

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/
Si no sabes adonde vas, es muy probable que acabes en otra parte.

  4. Re: add new acronym "AM"

    Daniel Gustafsson <daniel@yesql.se> — 2023-11-13T12:38:57Z

    
> On 13 Nov 2023, at 12:20, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
> 
> On 2023-Nov-13, Daniel Gustafsson wrote:
> 
>> That's a fair point.  It's sort of hard to refer back from the acronym list
>> though since we don't have a single Access Method section but instead one for
>> Indexes and one for Relations.  In the attached diff I propose that we add a
>> glossary entry for Access Method (suggested better wording much appreciated)
>> which the acronym can refer to.  Being such a core concept it doesn't seem like
>> a bad idea to explain it.
> 
> +1 for a glossary entry.
> 
> +     Access methods are the interfaces which
> +     <productname>PostgreSQL</productname> use in order to access relations
> +     and indexes. This abstraction allows for adding support for new
> +     types of tuple storage. For more information, see <xref linkend="indexam" />
> +     and <xref linkend="tableam" />.
> 
> We don't start the glossary definition with the term we're defining.
> For example, we say
>  Atomicity
>  The property of a transaction that ...
> we don't say
>  Atomicity
>  Atomicity is the property of ...
> 
> So you would want your definition to be something like
> "Interfaces which PostgreSQL use to ..."
> 
> I'd say "data in tables and indexes" rather than "relations and
> indexes", and "data storage" instead of "tuple storage".
> 
> "For more information" should be its own <para>.

Thanks, that makes it a lot better. v2 with the above changes attached.

--
Daniel Gustafsson