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

> On 21 Mar 2025, at 21:55, Andres Freund <andres(at)anarazel(dot)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