pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedTLS docs fixes for <programlisting>
4+ messages / 2 participants
[nested] [flat]
Commits from this thread:
2020-05-14 07451e1f1a Doc: Fix some inconsistencies with markups
* TLS docs fixes for <programlisting>
@ 2020-05-13 21:07 Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 4+ messages in thread
From: Daniel Gustafsson @ 2020-05-13 21:07 UTC (permalink / raw)
To: pgsql-docs
While working with TLS I noticed that the password callback definition had an
extra newline in the programlisting in the docs. Since the <programlisting>
has been indented with the textblock, the newline comes from whitespace being
significant. The attached 0001 fixes by instead anchoring <programlisting> on
column zero like how most of the docs do it. Grepping around I found one more
instance of the same pattern which is also included.
The "Enter PEM pass phrase" prompt was referred to in one place with <literal>
and one with <programlisting>, the 0002 settles on using <literal> for both
since IMO that makes the docs more readable. While there, it also fixes the
spelling of "pass phrase" from the two variations we had (of which none was the
correct one from src/backend/libpq/be-secure-openssl.c as well as the OpenSSL
file crypto/pem/pem_lib.c).
cheers ./daniel
Attachments: download all (2 files, .tar.gz)
0002-doc-fix-PEM-prompt-markup.patch (application/octet-stream, 1.9K) download
From 734dc5dc853769a750007b95b53c89d9fbfc8b5f Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Wed, 13 May 2020 16:46:49 +0200
Subject: [PATCH 2/2] doc: fix PEM prompt markup
The same document was using literal and programlisting for showing
the PEM pass phrase prompt, settle on using a single way to render
the same thing. Also reword the actual prompt as both occurrences
had different spelling with neither being wbat is actually used.
---
doc/src/sgml/libpq.sgml | 7 ++-----
1 file changed, 2 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index c404429ae9..75c7c5837b 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1668,7 +1668,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
</para>
<para>
Specifying this parameter with any non-empty value suppresses the
- <literal>Enter PEM passphrase:</literal>
+ <literal>Enter PEM pass phrase:</literal>
prompt that OpenSSL will emit by default when an encrypted client
certificate key is provided to <literal>libpq</literal>.
</para>
@@ -7667,10 +7667,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
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
- <programlisting>
- Enter PEM Passphrase:
- </programlisting>
+ OpenSSL 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 <xref linkend="libpq-pqsetsslkeypasshook"/>.
--
2.21.1 (Apple Git-122.3)
=
0001-doc-anchor-programlisting-on-column-zero.patch (application/octet-stream, 2.2K) download
From 0cad03da12c52495c335a1b839c79752ba602c8f Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Wed, 13 May 2020 16:15:46 +0200
Subject: [PATCH 1/2] doc: anchor programlisting on column zero
Whitespace is significant in programlisting blocks, so when used
indented they render a blank line after the content. Fix by anchoring
the blocks on column zero like how we do in most places of the docs.
---
doc/src/sgml/libpq.sgml | 6 +++---
doc/src/sgml/postgres-fdw.sgml | 8 ++++----
2 files changed, 7 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 5892367c61..c404429ae9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -790,9 +790,9 @@ void PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook);
</synopsis>
The application passes a pointer to a callback function with signature:
- <programlisting>
- int callback_fn(char *buf, int size, PGconn *conn);
- </programlisting>
+<programlisting>
+int callback_fn(char *buf, int size, PGconn *conn);
+</programlisting>
which <literal>libpq</literal> will then call <emphasis>instead of</emphasis>
its default <function>PQdefaultSSLKeyPassHook</function> handler. The callback
should determine the password for the key and copy it to result-buffer
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 94992be427..eab2cc9378 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -151,10 +151,10 @@
<para>
A superuser may override this check on a per-user-mapping basis by setting
the user mapping option <literal>password_required 'false'</literal>, e.g.
- <programlisting>
- ALTER USER MAPPING FOR some_non_superuser SERVER loopback_nopw
- OPTIONS (ADD password_required 'false');
- </programlisting>
+<programlisting>
+ALTER USER MAPPING FOR some_non_superuser SERVER loopback_nopw
+OPTIONS (ADD password_required 'false');
+</programlisting>
To prevent unprivileged users from exploiting the authentication rights
of the unix user the postgres server is running as to escalate to superuser
rights, only the superuser may set this option on a user mapping.
--
2.21.1 (Apple Git-122.3)
=
* Re: TLS docs fixes for <programlisting>
@ 2020-05-14 02:17 Michael Paquier <michael@paquier.xyz>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 4+ messages in thread
From: Michael Paquier @ 2020-05-14 02:17 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs
On Wed, May 13, 2020 at 11:07:44PM +0200, Daniel Gustafsson wrote:
> While working with TLS I noticed that the password callback definition had an
> extra newline in the programlisting in the docs. Since the <programlisting>
> has been indented with the textblock, the newline comes from whitespace being
> significant. The attached 0001 fixes by instead anchoring <programlisting> on
> column zero like how most of the docs do it. Grepping around I found one more
> instance of the same pattern which is also included.
Indeed, I can see the difference. In what I spotted after applying
0001, you are patching the one in libpq.sgml as of 0002 but in a
different, correct, way, and I have spotted three more inconsistencies
within doc/src/sgml/datatype.sgml in the zone for timestamps.
> The "Enter PEM pass phrase" prompt was referred to in one place with <literal>
> and one with <programlisting>, the 0002 settles on using <literal> for both
> since IMO that makes the docs more readable. While there, it also fixes the
> spelling of "pass phrase" from the two variations we had (of which none was the
> correct one from src/backend/libpq/be-secure-openssl.c as well as the OpenSSL
> file crypto/pem/pem_lib.c).
Yeah, good catch. Let's fix that.
With everything I found on top of your stuff, I finish with the
attached. Does it look fine to you?
--
Michael
Attachments:
doc-fixes-daniel-v2.patch (text/x-diff, 4.1K) download
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index a8d0780387..86eb38cc8f 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2095,11 +2095,15 @@ January 8 04:05:06 1999 PST
<quote>+</quote> or <quote>-</quote> symbol and time zone offset after
the time. Hence, according to the standard,
- <programlisting>TIMESTAMP '2004-10-19 10:23:54'</programlisting>
+<programlisting>
+TIMESTAMP '2004-10-19 10:23:54'
+</programlisting>
is a <type>timestamp without time zone</type>, while
- <programlisting>TIMESTAMP '2004-10-19 10:23:54+02'</programlisting>
+<programlisting>
+TIMESTAMP '2004-10-19 10:23:54+02'
+</programlisting>
is a <type>timestamp with time zone</type>.
<productname>PostgreSQL</productname> never examines the content of a
@@ -2108,7 +2112,9 @@ January 8 04:05:06 1999 PST
ensure that a literal is treated as <type>timestamp with time
zone</type>, give it the correct explicit type:
- <programlisting>TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'</programlisting>
+<programlisting>
+TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
+</programlisting>
In a literal that has been determined to be <type>timestamp without time
zone</type>, <productname>PostgreSQL</productname> will silently ignore
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 5892367c61..75c7c5837b 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -790,9 +790,9 @@ void PQsetSSLKeyPassHook(PQsslKeyPassHook_type hook);
</synopsis>
The application passes a pointer to a callback function with signature:
- <programlisting>
- int callback_fn(char *buf, int size, PGconn *conn);
- </programlisting>
+<programlisting>
+int callback_fn(char *buf, int size, PGconn *conn);
+</programlisting>
which <literal>libpq</literal> will then call <emphasis>instead of</emphasis>
its default <function>PQdefaultSSLKeyPassHook</function> handler. The callback
should determine the password for the key and copy it to result-buffer
@@ -1668,7 +1668,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
</para>
<para>
Specifying this parameter with any non-empty value suppresses the
- <literal>Enter PEM passphrase:</literal>
+ <literal>Enter PEM pass phrase:</literal>
prompt that OpenSSL will emit by default when an encrypted client
certificate key is provided to <literal>libpq</literal>.
</para>
@@ -7667,10 +7667,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
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
- <programlisting>
- Enter PEM Passphrase:
- </programlisting>
+ OpenSSL 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 <xref linkend="libpq-pqsetsslkeypasshook"/>.
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 94992be427..eab2cc9378 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -151,10 +151,10 @@
<para>
A superuser may override this check on a per-user-mapping basis by setting
the user mapping option <literal>password_required 'false'</literal>, e.g.
- <programlisting>
- ALTER USER MAPPING FOR some_non_superuser SERVER loopback_nopw
- OPTIONS (ADD password_required 'false');
- </programlisting>
+<programlisting>
+ALTER USER MAPPING FOR some_non_superuser SERVER loopback_nopw
+OPTIONS (ADD password_required 'false');
+</programlisting>
To prevent unprivileged users from exploiting the authentication rights
of the unix user the postgres server is running as to escalate to superuser
rights, only the superuser may set this option on a user mapping.
* Re: TLS docs fixes for <programlisting>
@ 2020-05-14 07:38 Daniel Gustafsson <daniel@yesql.se>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 1 reply; 4+ messages in thread
From: Daniel Gustafsson @ 2020-05-14 07:38 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: pgsql-docs
> On 14 May 2020, at 04:17, Michael Paquier <michael@paquier.xyz> wrote:
>
> On Wed, May 13, 2020 at 11:07:44PM +0200, Daniel Gustafsson wrote:
>> While working with TLS I noticed that the password callback definition had an
>> extra newline in the programlisting in the docs. Since the <programlisting>
>> has been indented with the textblock, the newline comes from whitespace being
>> significant. The attached 0001 fixes by instead anchoring <programlisting> on
>> column zero like how most of the docs do it. Grepping around I found one more
>> instance of the same pattern which is also included.
>
> Indeed, I can see the difference. In what I spotted after applying
> 0001, you are patching the one in libpq.sgml as of 0002 but in a
> different, correct, way, and I have spotted three more inconsistencies
> within doc/src/sgml/datatype.sgml in the zone for timestamps.
Right, I omitted them to avoid churn since they are using <programlisting>
correctly, just in a different way from the rest of the docs. I'll leave the
call whether they should be included for consistency sake to you.
> With everything I found on top of your stuff, I finish with the
> attached. Does it look fine to you?
+1, thanks for picking it up!
cheers ./daniel
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: TLS docs fixes for <programlisting>
@ 2020-05-15 01:58 Michael Paquier <michael@paquier.xyz>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 4+ messages in thread
From: Michael Paquier @ 2020-05-15 01:58 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs
On Thu, May 14, 2020 at 09:38:09AM +0200, Daniel Gustafsson wrote:
> On 14 May 2020, at 04:17, Michael Paquier <michael@paquier.xyz> wrote:
>> With everything I found on top of your stuff, I finish with the
>> attached. Does it look fine to you?
>
> +1, thanks for picking it up!
Thanks, I have applied the previous version then as of 07451e1.
--
Michael
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2020-05-15 01:58 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-05-13 21:07 TLS docs fixes for <programlisting> Daniel Gustafsson <daniel@yesql.se>
2020-05-14 02:17 ` Michael Paquier <michael@paquier.xyz>
2020-05-14 07:38 ` Daniel Gustafsson <daniel@yesql.se>
2020-05-15 01:58 ` Michael Paquier <michael@paquier.xyz>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox