Re: SSL/TLS instead of SSL in docs

> On 18 Jun 2021, at 07:37, Michael Paquier <michael@paquier.xyz> wrote:
> 
> On Tue, Jun 15, 2021 at 03:59:18PM +0200, Daniel Gustafsson wrote:
>> While in there I added IMO missing items to the glossary and acronyms sections
>> as well as fixed up markup around OpenSSL.
>> 
>> This only deals with docs, but if this is deemed interesting then userfacing
>> messages in the code should use SSL/TLS as well of course.
> 
> +    <term><acronym>SNI</acronym></term>
> +    <listitem>
> +     <para>
> +      <link linkend="libpq-connect-sslsni">Server Name Indication</link>
> +     </para>
> +    </listitem>
> 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.

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

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?

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

--
Daniel Gustafsson		https://vmware.com/