Thread: acronym, glossary and other related matters in the docs

Hi,

I was trying to write some docs for an AIO related view. As part of that I
noticed that we referenced I/O a lot, but never defined it as an acronym or
had it in the glossary.  While adding those I got somewhat confused by things
that have confused me in the past:

1) When are we supposed to use <acronym>IDK</acronym> and when not? We seem to
   be extremely inconsistent. E.g.
   git grep -P 'WAL(?=\</acronym)' doc/|wc -l
   42
   git grep -P 'WAL(?!\</acronym)' doc/|wc -l
   904

   Given that, at least for html, <acronym> doesn't change the display, that's
   perhaps not too surprising. But if we don't do it consistently, perhaps we
   should just stop doing it at all?


2) We have glossary entries explaining acronyms, but we rarely reference
   them. Is there a reason for that?  It'd probably be silly to link glossary
   entries every time an acronym is used, often there are many uses close-by,
   but that doesn't mean we shouldn't ever do it?

   ISTM we should have a guideline for this.


3) Why are we referencing glossary entries mainly with glossterm? That ends up
   being rather verbose, because the link text has to be supplied. Afaict with
   our styling just using <xref> works nicely.

   Oddly enough we use <link> in one place in acronyms.sgml:
   <varlistentry>
    <term><acronym>AM</acronym></term>
    <listitem>
     <para>
      <link linkend="glossary-am">Access Method</link>
     </para>
    </listitem>
   </varlistentry>


4) We don't put the glossary entries in the index, despite that sometimes
   being the only place something is documented.

   E.g. "WAL writer" isn't anywhere in the index and we have no other docs for
   it.

   It's annoyingly repetitive, but

   <glossentry id="glossary-aio">
    <glossterm zone="glossary-aio">Asynchronous <acronym>I/O</acronym></glossterm>
    <acronym>AIO</acronym>
    <indexterm>
     <primary>Asynchronous <acronym>I/O</acronym></primary>
    </indexterm>
    ...

   does result in a:
     "Asynchronous I/O, Glossary"
   entry.


Greetings,

Andres Freund

> On 21 Mar 2025, at 21:55, Andres Freund <andres@anarazel.de> wrote:

> 1) When are we supposed to use <acronym>IDK</acronym> and when not? We seem to
>   be extremely inconsistent. E.g.
>   git grep -P 'WAL(?=\</acronym)' doc/|wc -l
>   42
>   git grep -P 'WAL(?!\</acronym)' doc/|wc -l
>   904
>
>   Given that, at least for html, <acronym> doesn't change the display, that's
>   perhaps not too surprising. But if we don't do it consistently, perhaps we
>   should just stop doing it at all?

I can't find a reference to it now, but I seem to recall a discussion which
ended with a recommendation to use <acronym>IDK</acronym> for the first use of
IDK in a "logical block" (a page, a set of linked <para>'s, a list etc etc),
and omit it for subsequent uses.  Basically, if <acronym /> one day would be
rendered differently the decoration should help the reader without turning the
documentation into a christmas tree.

--
Daniel Gustafsson