From 92eff52c83efaa686efd9415ee00eba70f906514 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Sat, 29 Aug 2020 01:28:03 +0200
Subject: [PATCH 1/2] docs: consistent markup for OpenSSL and SSL, v9

OpenSSL was mostly referred to with the "productname" tag, but also
with "application" as well without any markup at all. This moves to
using "productname" for all mentions as well as using "acronym" on
most mentions of SSL and its concepts.
---
 doc/src/sgml/config.sgml   |  6 +++---
 doc/src/sgml/libpq.sgml    | 24 ++++++++++++------------
 doc/src/sgml/pgcrypto.sgml |  8 ++++----
 doc/src/sgml/sslinfo.sgml  |  2 +-
 4 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 606e80df0e..032232e5d7 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1261,7 +1261,7 @@ include_dir 'conf.d'
           <term><literal>+3DES</literal></term>
           <listitem>
            <para>
-            The OpenSSL default order for <literal>HIGH</literal> is problematic
+            The <productname>OpenSSL</productname> default order for <literal>HIGH</literal> is problematic
             because it orders 3DES higher than AES128.  This is wrong because
             3DES offers less security than AES128, and it is also much
             slower.  <literal>+3DES</literal> reorders it after all other
@@ -1284,7 +1284,7 @@ include_dir 'conf.d'
        </para>
 
        <para>
-        Available cipher suite details will vary across OpenSSL versions.  Use
+        Available cipher suite details will vary across <productname>OpenSSL</productname> versions.  Use
         the command
         <literal>openssl ciphers -v 'HIGH:MEDIUM:+3DES:!aNULL'</literal> to
         see actual details for the currently installed <application>OpenSSL</application>
@@ -1337,7 +1337,7 @@ include_dir 'conf.d'
        </para>
 
        <para>
-        OpenSSL names for the most common curves are:
+        <productname>OpenSSL</productname> names for the most common curves are:
         <literal>prime256v1</literal> (NIST P-256),
         <literal>secp384r1</literal> (NIST P-384),
         <literal>secp521r1</literal> (NIST P-521).
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index a397073526..b932fdbaae 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -812,7 +812,7 @@ int callback_fn(char *buf, int size, PGconn *conn);
        its path will be in <literal>conn->sslkey</literal> when the callback
        is invoked. This will be empty if the default key path is being used.
        For keys that are engine specifiers, it is up to engine implementations
-       whether they use the OpenSSL password callback or define their own handling.
+       whether they use the <productname>OpenSSL</productname> password callback or define their own handling.
       </para>
 
       <para>
@@ -1672,13 +1672,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
        <para>
         Specifying this parameter with any non-empty value suppresses the
         <literal>Enter PEM pass phrase:</literal>
-        prompt that OpenSSL will emit by default when an encrypted client
+        prompt that <productname>OpenSSL</productname> will emit by default when an encrypted client
         certificate key is provided to <literal>libpq</literal>.
        </para>
        <para>
         If the key is not encrypted this parameter is ignored. The parameter has no
-        effect on keys specified by OpenSSL engines unless the engine uses the
-        OpenSSL password callback mechanism for prompts.
+        effect on keys specified by <productname>OpenSSL</productname> engines unless the engine uses the
+        <productname>OpenSSL</productname> password callback mechanism for prompts.
        </para>
        <para>
         There is no environment variable equivalent to this option, and no
@@ -2471,8 +2471,8 @@ void *PQsslStruct(const PGconn *conn, const char *struct_name);
       </para>
       <para>
        The struct(s) available depend on the SSL implementation in use.
-       For OpenSSL, there is one struct, available under the name "OpenSSL",
-       and it returns a pointer to the OpenSSL <literal>SSL</literal> struct.
+       For <productname>OpenSSL</productname>, there is one struct, available under the name "OpenSSL",
+       and it returns a pointer to the <productname>OpenSSL</productname> <literal>SSL</literal> struct.
        To use this function, code along the following lines could be used:
 <programlisting><![CDATA[
 #include <libpq-fe.h>
@@ -2516,7 +2516,7 @@ void *PQgetssl(const PGconn *conn);
       <para>
        This function is equivalent to <literal>PQsslStruct(conn, "OpenSSL")</literal>. It should
        not be used in new applications, because the returned struct is
-       specific to OpenSSL and will not be available if another SSL
+       specific to <productname>OpenSSL</productname> and will not be available if another <acronym>SSL</acronym>
        implementation is used. To check if a connection uses SSL, call
        <xref linkend="libpq-PQsslInUse"/> instead, and for more details about the
        connection, use <xref linkend="libpq-PQsslAttribute"/>.
@@ -7666,11 +7666,11 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
   <para>
    The key may be
    stored in cleartext or encrypted with a passphrase using any algorithm supported
-   by OpenSSL, like AES-128. If the key is stored encrypted, then the passphrase
+   by <productname>OpenSSL</productname>, like AES-128. If the key is stored encrypted, then the passphrase
    may be provided in the <xref linkend="libpq-connect-sslpassword"/> connection
    option. If an encrypted key is supplied and the <literal>sslpassword</literal>
    option is absent or blank, a password will be prompted for interactively by
-   OpenSSL with a <literal>Enter PEM pass phrase:</literal>
+   <productname>OpenSSL</productname> with a <literal>Enter PEM pass phrase:</literal>
    prompt if a TTY is available. Applications can override the client certificate
    prompt and the handling of the <literal>sslpassword</literal> parameter by supplying
    their own key password callback; see
@@ -7936,7 +7936,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto);
 
       <para>
        When <parameter>do_ssl</parameter> is non-zero, <application>libpq</application>
-       will initialize the <application>OpenSSL</application> library before first
+       will initialize the <productname>OpenSSL</productname> library before first
        opening a database connection.  When <parameter>do_crypto</parameter> is
        non-zero, the <literal>libcrypto</literal> library will be initialized.  By
        default (if <xref linkend="libpq-PQinitOpenSSL"/> is not called), both libraries
@@ -7945,7 +7945,7 @@ void PQinitOpenSSL(int do_ssl, int do_crypto);
       </para>
 
       <para>
-       If your application uses and initializes either <application>OpenSSL</application>
+       If your application uses and initializes either <productname>OpenSSL</productname>
        or its underlying <literal>libcrypto</literal> library, you <emphasis>must</emphasis>
        call this function with zeroes for the appropriate parameter(s)
        before first opening a database connection.  Also be sure that you
@@ -7967,7 +7967,7 @@ void PQinitSSL(int do_ssl);
        This function is equivalent to
        <literal>PQinitOpenSSL(do_ssl, do_ssl)</literal>.
        It is sufficient for applications that initialize both or neither
-       of <application>OpenSSL</application> and <literal>libcrypto</literal>.
+       of <productname>OpenSSL</productname> and <literal>libcrypto</literal>.
       </para>
 
       <para>
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index 6fd645aa70..36ba7b4041 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -45,7 +45,7 @@ digest(data bytea, type text) returns bytea
     <literal>sha224</literal>, <literal>sha256</literal>,
     <literal>sha384</literal> and <literal>sha512</literal>.
     If <filename>pgcrypto</filename> was built with
-    OpenSSL, more algorithms are available, as detailed in
+    <productname>OpenSSL</productname>, more algorithms are available, as detailed in
     <xref linkend="pgcrypto-with-without-openssl"/>.
    </para>
 
@@ -1162,8 +1162,8 @@ gen_random_uuid() returns uuid
    </para>
 
    <para>
-    When compiled with OpenSSL, there will be more algorithms available.
-    Also public-key encryption functions will be faster as OpenSSL
+    When compiled with <productname>OpenSSL</productname>, there will be more algorithms available.
+    Also public-key encryption functions will be faster as <productname>OpenSSL</productname>
     has more optimized BIGNUM functions.
    </para>
 
@@ -1239,7 +1239,7 @@ gen_random_uuid() returns uuid
    <orderedlist>
     <listitem>
      <para>
-      Any digest algorithm OpenSSL supports is automatically picked up.
+      Any digest algorithm <productname>OpenSSL</productname> supports is automatically picked up.
       This is not possible with ciphers, which need to be supported
       explicitly.
      </para>
diff --git a/doc/src/sgml/sslinfo.sgml b/doc/src/sgml/sslinfo.sgml
index 7d3fcb7167..195949f55a 100644
--- a/doc/src/sgml/sslinfo.sgml
+++ b/doc/src/sgml/sslinfo.sgml
@@ -174,7 +174,7 @@
      This function returns the value of the specified field in the
      certificate subject, or NULL if the field is not present.
      Field names are string constants that are
-     converted into ASN1 object identifiers using the OpenSSL object
+     converted into ASN1 object identifiers using the <productname>OpenSSL</productname> object
      database.  The following values are acceptable:
     </para>
 <literallayout class="monospaced">
-- 
2.21.1 (Apple Git-122.3)

