Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jKm2K-0002d3-SP for pgsql-hackers@arkaria.postgresql.org; Sat, 04 Apr 2020 16:52:49 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jKm2J-0003uZ-NY for pgsql-hackers@arkaria.postgresql.org; Sat, 04 Apr 2020 16:52:47 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jKm2J-0003uS-9y for pgsql-hackers@lists.postgresql.org; Sat, 04 Apr 2020 16:52:47 +0000 Received: from mail-ed1-x52e.google.com ([2a00:1450:4864:20::52e]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jKm2G-0007gJ-DM for pgsql-hackers@postgresql.org; Sat, 04 Apr 2020 16:52:46 +0000 Received: by mail-ed1-x52e.google.com with SMTP id cf14so13237656edb.13 for ; Sat, 04 Apr 2020 09:52:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=dtX/tdehtQ1PxvqVwymXvli9Ijq2t0x3USmQPMWkfww=; b=SLuezgZxhf+kZ8B+x23tVSgwV15d+62ViL8pqnHw9smQRXOGVQzR+9wZLBIQaDS1Qw CHhKVtoP7RBjRlyC1yJYtq098qwHmD9ld3nyYzIRanQcdBOxyz8cWzaEJavUEGh0rbfi 24Cfqys5v8radmrKbbi7YIH6wobOI8xvdr3YocIKAJMKvjXbyJzjC2POrF3Q96DLGT5k KUeQQ0zCHu1C+JgB48CUSA6xSTDRWa/BoenX9N0hyc0AlBDlx+9pvu2usl5gAyELX6iC n/GtS8480odUqbEsgfoxzklzwcqqQAPletMxhkBSje5SexaTDOGnO1xoCrPaIexSk9uu cXWQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=dtX/tdehtQ1PxvqVwymXvli9Ijq2t0x3USmQPMWkfww=; b=L3/crCgTTEZsfKTNCLM8e/uHUHqj4ILfzMkA/EHuacpbf6Tzmdjh4dNXu9Bv+/gCex o3mFOvpQCnQ/OWGy1Md8UsMJoyiCL1ABOsvzdXEkaZyEH+Ky269bQlwbirAV8qlUUKEl srnm5f9lRaSFBDiWQwQuZs4Oy7uAjHve4bsCydXB4/I8fNsWFdCcorQlyu6ci3zs14JM frA6oqpFpzfCocAiKWi9o/xaZjc4WCWbCkuFingPMKMom0VqbqMzvMD0zu4+jU7uill4 AGU6RBEJ7vaO/UAaL6lmtMekEpvKKtzZezuFggT31eBMHyArgjzQ1n4q12hQujUHyztB escw== X-Gm-Message-State: AGi0PuaeRHzkPYsmsdXTdMSZPphR3tJH2c2moHXX5cIdIM8e0DSt4sZs AaEMiRN6fJij2CGSyqxqYzq0oHP+ixBYY/hTTEw= X-Google-Smtp-Source: APiQypKJrJm97GfKbVQTyPHlkx5TJGjwccAusFWADHucKq1kIXsJEBlGM7ZuLA3CZ4VFn9rxUvDzaZEfj421elE28a4= X-Received: by 2002:a17:906:3017:: with SMTP id 23mr14037335ejz.361.1586019161354; Sat, 04 Apr 2020 09:52:41 -0700 (PDT) MIME-Version: 1.0 References: <7b9b469e804777ac9df4d37716db935e@xs4all.nl> <20200403205143.GA7961@alvherre.pgsql> <20200403210120.GA12283@telsasoft.com> In-Reply-To: From: Corey Huinker Date: Sat, 4 Apr 2020 12:52:29 -0400 Message-ID: Subject: Re: Add A Glossary To: Fabien COELHO Cc: Justin Pryzby , Alvaro Herrera , Erik Rijkers , =?UTF-8?Q?J=C3=BCrgen_Purtz?= , Roger Harkavy , pgsql-hackers@postgresql.org, Michael Paquier Content-Type: multipart/alternative; boundary="000000000000b8357705a279dc17" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --000000000000b8357705a279dc17 Content-Type: text/plain; charset="UTF-8" On Sat, Apr 4, 2020 at 2:55 AM Fabien COELHO 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. --000000000000b8357705a279dc17 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Sat, Apr 4, 2020 at 2:55 AM Fabien COE= LHO <coelho@cri.ensmp.fr> = wrote:

> BTW it's now visible at:
> https://www.postgresql.org/docs/devel/glossa= ry.html
=C2=A0
Nice. I went looking for it y= esterday and the docs hadn't rebuilt yet.
=C2=A0
ISTM that occurrences of these w= ords 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 gloss= ary-foo. We would then go about gloss-linking those pages as appropriate, b= ut only a few pages at a time to keep scope sane. Also, I'm unclear abo= ut the circumstances under which we should _not_ tag a term. I remember hea= ring that we should only tag it on the first usage, but is that per section= or per page?
=C2=A0
As the definitions are short and to the point, maybe the HTM= L display
could (also) "hover" the definitions when the mouse passes over t= he 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 w= ould want to just carry over the first sentence or so with a ... to avoid c= luttering the screen with my overblown definition of a sequence.
<= div>I suggest we pursue this idea in another thread, as we'd probably w= ant to do it for acronyms as well.
=C2=A0

"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.
=C2=A0
Entries cou= ld link to relevant wikipedia pages, like the acronyms section
does?

They could. I opted not to do tha= t because each external link invites debate about how authoritative that li= nk is, which is easier to do with acronyms. Now that the glossary is a real= ity, it's easier to have those discussions.
--000000000000b8357705a279dc17--