> On 18 Jun 2021, at 07:37, Michael Paquier <mich...@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/
v2-0002-docs-Replace-usage-of-SSL-with-SSL-TLS.patch
Description: Binary data
v2-0001-docs-SSL-TLS-related-acronyms-and-glossary.patch
Description: Binary data
