Thread: [PATCH] Documentation: Fix minor grammatical and formatting issues
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,
Attachment
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
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
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