Thread: TLS docs fixes for
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
Attachment
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
Attachment
> 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
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