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-21 11:23:56 |
Message-ID: | 4CF474F4-A108-4CC6-A813-075FF7B49DC9@yesql.se |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-hackers |
> On 18 Jun 2021, at 07:37, Michael Paquier <michael(at)paquier(dot)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/
Attachment | Content-Type | Size |
---|---|---|
v2-0002-docs-Replace-usage-of-SSL-with-SSL-TLS.patch | application/octet-stream | 73.7 KB |
v2-0001-docs-SSL-TLS-related-acronyms-and-glossary.patch | application/octet-stream | 3.9 KB |
From | Date | Subject | |
---|---|---|---|
Next Message | John Naylor | 2021-06-21 11:27:10 | Re: disfavoring unparameterized nested loops |
Previous Message | David Rowley | 2021-06-21 11:19:45 | Is the testing a bit too light on GROUP BY DISTINCT? |