From: Jonathan S. Katz <jkatz@postgresql.org>
To: Daniel Gustafsson <daniel@yesql.se>
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
Cc: Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: confusing positioning of notes in connection settings
Date: Mon, 5 Jun 2023 13:10:01 -0400
Message-ID: <739043ea-9fe8-3fa5-ed10-aa988eaeb121@postgresql.org> (raw)
In-Reply-To: <A21C7848-0B4A-4216-A528-92B41F220A76@yesql.se>
References: <6f825d42-a1ce-492a-2ea7-c83e6e65fa8b@postgresql.org>
<4e34fcb4-6791-0266-7352-27b769c478f9@enterprisedb.com>
<D70737D3-C949-471A-9471-9E2C22C428F4@yesql.se>
<39202431-DF62-42E2-B0C1-500C93AD37C8@yesql.se>
<ab7511ea-a089-2445-f64d-0bf72ebb7bc4@enterprisedb.com>
<A21C7848-0B4A-4216-A528-92B41F220A76@yesql.se>
On 5/31/23 7:53 AM, Daniel Gustafsson wrote:
>> On 31 May 2023, at 13:16, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
>
>> The first two hunks are pretty straightforward, they just move the existing text around.
>>
>> For the other two, which are not supported on Windows, I added an explicit parenthetical note. We don't list which of the Unix-like platforms support the respective options, but I suspect that it's all of them in practice? (Otherwise we should be more explicit.) So I think calling out Windows explicitly is sensible, also considering that the first two settings are supported on Windows but the latter two are not.
>
> I think this is a clear improvement over the current docs.
+1.
Small nit:
"which does not include Windows" =>
"which is not supported on Windows"
(in two places)
> Should we call out Windows explicitly in the same way in the corresponding
> options in the libpq connection string param docs as well?
Probably, but I see language like this:
"It is only supported on systems where TCP_USER_TIMEOUT is available; on
other systems, it has no effect."
If this is really only unsupported / has different settings on Windows,
I think it's OK to call that out. The original gripe was about
readability, but if we think the description in the other settings is no
clear enough, we can edit it.
Jonathan
Attachments:
[application/pgp-signature] OpenPGP_signature (839B, ../739043ea-9fe8-3fa5-ed10-aa988eaeb121@postgresql.org/2-OpenPGP_signature)
download
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: jkatz@postgresql.org, daniel@yesql.se, peter.eisentraut@enterprisedb.com, pgsql-docs@lists.postgresql.org
Subject: Re: confusing positioning of notes in connection settings
In-Reply-To: <739043ea-9fe8-3fa5-ed10-aa988eaeb121@postgresql.org>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
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