Horton
Menu

Thread

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. Doc: reword text explaining the --maintenance-db option

  2. Doc: various fixups

  3. Doc: fix incorrect punctuation

  1. [PATCH] Documentation: Fix minor grammatical and formatting issues

    Noboru Saito <noborusai@gmail.com> — 2025-04-21T03:05:32Z

    Hi PostgreSQL Hackers,

I'm a member of the PostgreSQL Japanese documentation translation
team. While working on translations,
I've identified several minor grammatical and formatting issues in the
English documentation.
Please review them.

1. Remove unnecessary blank lines (blankline.diff)
2. Fix repeated "to to" in several command reference files (toto.diff)
3. Fix period instead of comma in enumeration (comma.diff)
4. Standardize inline tags in libpq documentation (tagmiss.diff)
5. Remove redundant "that that" constructions (thatthat.diff)

These are all simple, self-explanatory fixes that improve readability
and consistency.
The attached patches correct these issues across multiple documentation files.

Thank you,

  2. Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

    David Rowley <dgrowleyml@gmail.com> — 2025-04-21T04:03:09Z

    On Mon, 21 Apr 2025 at 15:06, Noboru Saito <noborusai@gmail.com> wrote:
> 1. Remove unnecessary blank lines (blankline.diff)

Looks good.

> 2. Fix repeated "to to" in several command reference files (toto.diff)

-        Specifies the name of the database to connect to to discover which
+        Specifies the name of the database to connect to discover which

What's there is acceptable English, but it's maybe confusing to a
non-native speaker and might be worth adjusting so it's easier to
parse. "connect to to discover" is just short for "connect to in order
to discover". If it's confusing, maybe we could rephrase the whole
sentence. How about:

"When the <option>-a</option>/<option>--all</option> is used, connect
to this database to gather the list of databases to vacuum."

> 3. Fix period instead of comma in enumeration (comma.diff)

Looks good.

> 4. Standardize inline tags in libpq documentation (tagmiss.diff)

Looks good.

> 5. Remove redundant "that that" constructions (thatthat.diff)

I don't see anything wrong here. [1] does a better job of explaining
#5 than I can.

David

[1] https://english.stackexchange.com/questions/492349/is-my-use-of-that-that-in-this-sentence-gramaticaly-correct

  3. Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

    Noboru Saito <noborusai@gmail.com> — 2025-04-21T20:53:25Z

    Thank you for the review! I appreciate your detailed feedback.

Regarding "to to" and "that that", I agree that they might be
technically acceptable.
However, I personally find them a bit harder to parse and they
increase the chance of misreading for me.
Your suggested alternative for "to to" is much clearer!

Ultimately, if leaving them as-is is perfectly fine, I'm happy to
defer to your judgment.
But I would certainly welcome the improvement if you decide to revise
those phrases.

Thanks again for your time and consideration.

2025年4月21日(月) 13:03 David Rowley <dgrowleyml@gmail.com>:
>
> On Mon, 21 Apr 2025 at 15:06, Noboru Saito <noborusai@gmail.com> wrote:
> > 1. Remove unnecessary blank lines (blankline.diff)
>
> Looks good.
>
> > 2. Fix repeated "to to" in several command reference files (toto.diff)
>
> -        Specifies the name of the database to connect to to discover which
> +        Specifies the name of the database to connect to discover which
>
> What's there is acceptable English, but it's maybe confusing to a
> non-native speaker and might be worth adjusting so it's easier to
> parse. "connect to to discover" is just short for "connect to in order
> to discover". If it's confusing, maybe we could rephrase the whole
> sentence. How about:
>
> "When the <option>-a</option>/<option>--all</option> is used, connect
> to this database to gather the list of databases to vacuum."
>
> > 3. Fix period instead of comma in enumeration (comma.diff)
>
> Looks good.
>
> > 4. Standardize inline tags in libpq documentation (tagmiss.diff)
>
> Looks good.
>
> > 5. Remove redundant "that that" constructions (thatthat.diff)
>
> I don't see anything wrong here. [1] does a better job of explaining
> #5 than I can.
>
> David
>
> [1] https://english.stackexchange.com/questions/492349/is-my-use-of-that-that-in-this-sentence-gramaticaly-correct

  4. Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

    David Rowley <dgrowleyml@gmail.com> — 2025-04-22T00:07:55Z

    On Tue, 22 Apr 2025 at 08:53, Noboru Saito <noborusai@gmail.com> wrote:
> Regarding "to to" and "that that", I agree that they might be
> technically acceptable.
> However, I personally find them a bit harder to parse and they
> increase the chance of misreading for me.
> Your suggested alternative for "to to" is much clearer!
>
> Ultimately, if leaving them as-is is perfectly fine, I'm happy to
> defer to your judgment.
> But I would certainly welcome the improvement if you decide to revise
> those phrases.

I've pushed all your suggestions aside from the toto.diff and thatthat.diff.

I noticed your tagmiss.diff was moving things in the wrong direction.
After looking at usages of <symbol>, we seem to use that for
preprocessor #defines. The following shows we're more consistent with
using <symbol> for these:

$ git grep -F "<symbol>BLCKSZ</symbol>" | wc -l
26

$ git grep -F "<literal>BLCKSZ</literal>" | wc -l
1

There's probably a bigger project there for anyone who feels strongly
enough about this and wants to harvest our list of #defines and check
how we reference those in the docs. I resisted fixing that one as it's
probably the tip of the iceberg.

Please see the attached patch which aims to improve the "to to"
instances (also a compiled .html for ease of review).

Does anyone have any opinion on the wording I'm proposing in the attached?

David

  5. Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

    David G. Johnston <david.g.johnston@gmail.com> — 2025-04-22T00:27:51Z

    On Monday, April 21, 2025, David Rowley <dgrowleyml@gmail.com> wrote:

>
> Does anyone have any opinion on the wording I'm proposing in the attached?
>

I like it.  It removes the problematic wording and moves the reference to
—all closer to the front to aid in skimming.

David J.

  6. Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

    David Rowley <dgrowleyml@gmail.com> — 2025-04-22T03:00:39Z

    On Tue, 22 Apr 2025 at 12:27, David G. Johnston
<david.g.johnston@gmail.com> wrote:
> On Monday, April 21, 2025, David Rowley <dgrowleyml@gmail.com> wrote:
>> Does anyone have any opinion on the wording I'm proposing in the attached?
>
> I like it.  It removes the problematic wording and moves the reference to —all closer to the front to aid in skimming.

Thanks for looking. I've pushed and backpatched that down to v13. I
felt it was worth keeping it the same in all supported versions.

David