Re: SSL/TLS instead of SSL in docs

From: Daniel Gustafsson <daniel(at)yesql(dot)se>
To: Michael Paquier <michael(at)paquier(dot)xyz>
Cc: Bruce Momjian <bruce(at)momjian(dot)us>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Magnus Hagander <magnus(at)hagander(dot)net>, Andrew Dunstan <andrew(dot)dunstan(at)2ndquadrant(dot)com>, Jeff Davis <pgsql(at)j-davis(dot)com>, PostgreSQL Developers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Re: SSL/TLS instead of SSL in docs
Date: 2021-06-24 11:53:47
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

> On 22 Jun 2021, at 06:37, Michael Paquier <michael(at)paquier(dot)xyz> wrote:
> On Mon, Jun 21, 2021 at 01:23:56PM +0200, Daniel Gustafsson wrote:
>> On 18 Jun 2021, at 07:37, Michael Paquier <michael(at)paquier(dot)xyz> wrote:
>>> It looks inconsistent to me to point to the libpq documentation to get
>>> the details about SNI. Wouldn't is be better to have an item in the
>>> glossary that refers to the bits of RFC 6066, and remove the reference
>>> of the RPC from the libpq page?
>> I opted for a version with SNI in the glossary but without a link to the RFC
>> since no definitions in the glossary has ulinks.
> Okay, but why making all this complicated if it can be simple? If I
> read the top of the page, the description of the glossary refers more
> to terms that apply to PostgreSQL and RDBMs in general. I think that
> something like the attached is actually more adapted, where there are
> acronyms for SNI and MITM, and where the references we have in the
> libpq docs are moved to the page for acronyms. That's consistent with
> what we do now for the existing acronyms SSL and TLS, and there does
> not seem to need any references to all those terms in the glossary.

The attached v3 does it this way.

>>> - to present a valid (trusted) SSL certificate, while
>>> + to present a valid (trusted) <acronym>SSL</acronym>/<acronym>TLS</acronym> certificate, while
>>> This style with two acronyms for what we want to be one thing is
>>> heavy. Could it be better to just have one single acronym called
>>> SSL/TLS that references both parts?
>> Maybe, I don't know. I certainly don't prefer the way which is in the patch
>> but I also think it's the most "correct" way so I opted for that to start the
>> discussion. If we're fine with one acronym tag for the combination then I'm
>> happy to change to that.
> That feels a bit more natural to me to have SSL/TLS in the contexts
> where they apply as a single keyword. Do we have actually sections in
> the docs where only one of them apply, like some protocol references?

Yes, there are a few but not too many. Whenever the protocol is refererred to
and not the concept of an encrypted connection, just the applicable term is

The attached v3 wraps SSL/TLS in a single acronym block, which for sure is more
pleasing to the eye when working with the docs, but I still have no idea which
version technically is the most correct.

>> A slightly more invasive idea would be to not have acronyms at all and instead
>> move the ones that do benefit from clarification to the glossary? ISTM that
>> having a brief description of terms and not just the expansion is beneficial to
>> the users. That would however be for another thread, but perhaps thats worth
>> discussing?
> Not sure about this bit. That's a more general topic for sure, but I
> also like the separation we have not between the glossary and the
> acronyms. Having an entry in one does not make necessary the same
> entry in the other, and vice-versa.

It doesn't, I'm just not convinced that the acronyms page is consulted all too
frequently anymore to provide much value. I might be totally wrong though.
Either way, thats (potentially) for a separate discussion.

Daniel Gustafsson

Attachment Content-Type Size
v3-0002-Docs-Replace-usage-of-SSL-with-SSL-TLS.patch application/octet-stream 70.8 KB
v3-0001-Docs-SSL-TLS-related-acronyms.patch application/octet-stream 2.9 KB

In response to


Browse pgsql-hackers by date

  From Date Subject
Next Message Guillaume Lelarge 2021-06-24 11:57:09 Weird use of parentheses in the manual
Previous Message Richard Guo 2021-06-24 09:50:41 Using each rel as both outer and inner for JOIN_ANTI