Re: SSL/TLS instead of SSL in docs

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.

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

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

>> Patch 0003, for the <productname> markups with OpenSSL, included one
>> SSL/TLS entry.
>
> Ugh, sorry, that must've been a git add -p fat-finger.

The extra SSL/TLS entry was on one of the files changed f80979f, so
git add has been working just fine :)
--
Michael