> On 22 Jun 2021, at 06:37, Michael Paquier <mich...@paquier.xyz> wrote: > > On Mon, Jun 21, 2021 at 01:23:56PM +0200, Daniel Gustafsson wrote: >> On 18 Jun 2021, at 07:37, Michael Paquier <mich...@paquier.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 used. 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 https://vmware.com/
v3-0002-Docs-Replace-usage-of-SSL-with-SSL-TLS.patch
Description: Binary data
v3-0001-Docs-SSL-TLS-related-acronyms.patch
Description: Binary data
