| From: | Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> |
|---|---|
| To: | Corey Huinker <corey(dot)huinker(at)gmail(dot)com> |
| Cc: | Justin Pryzby <pryzby(at)telsasoft(dot)com>, Alvaro Herrera <alvherre(at)2ndquadrant(dot)com>, Erik Rijkers <er(at)xs4all(dot)nl>, Jürgen Purtz <juergen(at)purtz(dot)de>, Roger Harkavy <rogerharkavy(at)gmail(dot)com>, pgsql-hackers(at)postgresql(dot)org, Michael Paquier <michael(at)paquier(dot)xyz> |
| Subject: | Re: Add A Glossary |
| Date: | 2020-04-05 07:38:17 |
| Message-ID: | alpine.DEB.2.21.2004050925090.16227@pseudo |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-docs pgsql-hackers |
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.
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Jürgen Purtz | 2020-04-05 08:41:44 | Re: Add A Glossary |
| Previous Message | Corey Huinker | 2020-04-04 16:52:29 | Re: Add A Glossary |
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Peter Eisentraut | 2020-04-05 08:13:44 | Re: potential stuck lock in SaveSlotToPath() |
| Previous Message | Andres Freund | 2020-04-05 07:18:36 | Comment explaining why vacuum needs to push snapshot seems insufficient. |