Date: Sun, 5 Apr 2020 09:38:17 +0200 (CEST)
From: Fabien COELHO <coelho@cri.ensmp.fr>
To: Corey Huinker <corey.huinker@gmail.com>
cc: Justin Pryzby <pryzby@telsasoft.com>,
    Alvaro Herrera <alvherre@2ndquadrant.com>, Erik Rijkers <er@xs4all.nl>,
    =?ISO-8859-15?Q?J=FCrgen_Purtz?= <juergen@purtz.de>,
    Roger Harkavy <rogerharkavy@gmail.com>, pgsql-hackers@postgresql.org,
    Michael Paquier <michael@paquier.xyz>
Subject: Re: Add A Glossary
In-Reply-To: 
 <CADkLM=eLB=jLA=JK7ErAXdmvqsGouGChtVdFHkhVmELnyDxHXA@mail.gmail.com>
Message-ID: <alpine.DEB.2.21.2004050925090.16227@pseudo>
References: <7b9b469e804777ac9df4d37716db935e@xs4all.nl>
 <20200403205143.GA7961@alvherre.pgsql> <20200403210120.GA12283@telsasoft.com>
 <alpine.DEB.2.21.2004040832220.16227@pseudo>
 <CADkLM=eLB=jLA=JK7ErAXdmvqsGouGChtVdFHkhVmELnyDxHXA@mail.gmail.com>
User-Agent: Alpine 2.21 (DEB 202 2017-01-01)
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII; format=flowed
Precedence: bulk


Hi Corey,

>> 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.

Id go for scripting the thing.

Should the glossary be backpatched, to possibly ease doc patchpatches?

> Also, I'm unclear about the circumstances under which we should _not_ 
> tag a term.

At least when then are explained locally.

> I remember hearing that we should only tag it on the first usage, but is 
> that per section or per page?

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).

The following worked fine:

   <html><head><title>Title Tag Test</title></head>
   <body>The <a href="acid.html" title="ACID stands for Atomic, Consistent, Isolated & Durable">ACID</a>
   property is great.
   </body></html>

So basically the def can be put on the glossary link, however retrieving 
the definition should be automatic.

> 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.

Dunno. The definitions are quite short, maybe the can fit whole.

> I suggest we pursue this idea in another thread, as we'd probably want to
> do it for acronyms as well.

Or not. I'd test committer temperature before investing time because it 
would mean that backpatching the doc would be a little harder.

>> 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.

Ok.

-- 
Fabien.