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

> 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