Re: confusing positioning of notes in connection settings

From: "Jonathan S(dot) Katz" <jkatz(at)postgresql(dot)org>
To: Daniel Gustafsson <daniel(at)yesql(dot)se>, Peter Eisentraut <peter(dot)eisentraut(at)enterprisedb(dot)com>
Cc: Pg Docs <pgsql-docs(at)lists(dot)postgresql(dot)org>
Subject: Re: confusing positioning of notes in connection settings
Date: 2023-06-05 17:10:01
Message-ID: 739043ea-9fe8-3fa5-ed10-aa988eaeb121@postgresql.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

On 5/31/23 7:53 AM, Daniel Gustafsson wrote:
>> On 31 May 2023, at 13:16, Peter Eisentraut <peter(dot)eisentraut(at)enterprisedb(dot)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

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Erik Rijkers 2023-06-05 17:12:35 Re: PostgreSQL 16 release notes: could cloud
Previous Message Daniel Westermann (DWE) 2023-06-05 15:54:31 Re: PostgreSQL 16 release notes: could cloud