Re: Add A Glossary

On Sat, Apr 4, 2020 at 2:55 AM Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> wrote:

>
> > BTW it's now visible at:
> > https://www.postgresql.org/docs/devel/glossary.html

Nice. I went looking for it yesterday and the docs hadn't rebuilt yet.

> ISTM that occurrences of these words elsewhere in the documentation should
> link to the glossary definitions?
>

Yes, that's a big project. I was considering writing a script to compile
all the terms as search terms, paired with their glossary ids, and then
invoke git grep to identify all pages that have term FOO but don't have
glossary-foo. We would then go about gloss-linking those pages as
appropriate, but only a few pages at a time to keep scope sane. Also, I'm
unclear about the circumstances under which we should _not_ tag a term. I
remember hearing that we should only tag it on the first usage, but is that
per section or per page?

> As the definitions are short and to the point, maybe the HTML display
> could (also) "hover" the definitions when the mouse passes over the word,
> using the "title" attribute?
>

I like that idea, if it doesn't conflict with accessibility standards
(maybe that's just titles on images, not sure).
I suspect we would want to just carry over the first sentence or so with a
... to avoid cluttering the screen with my overblown definition of a
sequence.
I suggest we pursue this idea in another thread, as we'd probably want to
do it for acronyms as well.

>
> "ACID" does not appear as an entry, nor in the acronyms sections. Also no
> DCL, although DML & DDL are in acronyms.
>

It needs to be in the acronyms page, and in light of all the docbook
wizardry that I've learned from Alvaro, those should probably get their own
acronym-foo ids as well. The cutoff date for 13 fast approaches, so it
might be for 14+ unless doc-only patches are treated differently.

> Entries could link to relevant wikipedia pages, like the acronyms section
> does?
>

They could. I opted not to do that because each external link invites
debate about how authoritative that link is, which is easier to do with
acronyms. Now that the glossary is a reality, it's easier to have those
discussions.