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
