[PATCH] Documentation: Fix minor grammatical and formatting issues

Started by Noboru Saito9 months ago6 messages
#1Noboru Saito
noborusai@gmail.com
5 attachment(s)

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,

Attachments:

tagmiss.difftext/x-patch; charset=US-ASCII; name=tagmiss.diffDownload
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 3be66789ba7..4162f5d7c74 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -342,7 +342,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
        valid <structname>PGconn</structname> pointer is returned (though not
        yet representing a valid connection to the database).  Next
        call <literal>PQstatus(conn)</literal>.  If the result
-       is <symbol>CONNECTION_BAD</symbol>, the connection attempt has already
+       is <literal>CONNECTION_BAD</literal>, the connection attempt has already
        failed, typically because of invalid connection parameters.
       </para>
 
@@ -377,8 +377,8 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
 
       <para>
        At any time during connection, the status of the connection can be
-       checked by calling <xref linkend="libpq-PQstatus"/>. If this call returns <symbol>CONNECTION_BAD</symbol>, then the
-       connection procedure has failed; if the call returns <function>CONNECTION_OK</function>, then the
+       checked by calling <xref linkend="libpq-PQstatus"/>. If this call returns <literal>CONNECTION_BAD</literal>, then the
+       connection procedure has failed; if the call returns <literal>CONNECTION_OK</literal>, then the
        connection is ready.  Both of these states are equally detectable
        from the return value of <function>PQconnectPoll</function>, described above. Other states might also occur
        during (and only during) an asynchronous connection procedure. These
@@ -1922,7 +1922,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>sslkeylogfile</literal></term>
       <listitem>
        <para>
-        This parameter specifies the location where <literal>libpq</literal>
+        This parameter specifies the location where <application>libpq</application>
         will log keys used in this SSL context.  This is useful for debugging
         <productname>PostgreSQL</productname> protocol interactions or client
         connections using network inspection tools like
@@ -1956,7 +1956,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         <literal>Enter PEM pass phrase:</literal>
         prompt that <productname>OpenSSL</productname> will emit by default
         when an encrypted client certificate key is provided to
-        <literal>libpq</literal>.
+        <application>libpq</application>.
        </para>
        <para>
         If the key is not encrypted this parameter is ignored. The parameter
@@ -6626,9 +6626,9 @@ PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn);
       <para>
        At any time during connection, the status of the connection can be
        checked by calling <xref linkend="libpq-PQcancelStatus"/>.
-       If this call returns <symbol>CONNECTION_BAD</symbol>, then
+       If this call returns <literal>CONNECTION_BAD</literal>, then
        the cancel procedure has failed; if the call returns
-       <function>CONNECTION_OK</function>, then cancel request was
+       <literal>CONNECTION_OK</literal>, then cancel request was
        successfully dispatched.
        Both of these states are equally detectable from the return value of
        <function>PQcancelPoll</function>, described above.
@@ -8283,7 +8283,7 @@ size_t PQresultMemorySize(const PGresult *res);
 
     <listitem>
      <para>
-      Return the version of <productname>libpq</productname> that is being used.
+      Return the version of <application>libpq</application> that is being used.
 <synopsis>
 int PQlibVersion(void);
 </synopsis>
thatthat.difftext/x-patch; charset=US-ASCII; name=thatthat.diffDownload
diff --git a/doc/src/sgml/custom-scan.sgml b/doc/src/sgml/custom-scan.sgml
index a200d502cdd..a49c07c27b3 100644
--- a/doc/src/sgml/custom-scan.sgml
+++ b/doc/src/sgml/custom-scan.sgml
@@ -224,7 +224,7 @@ typedef struct CustomScan
   <para>
    Plan trees must be able to be duplicated using <function>copyObject</function>,
    so all the data stored within the <quote>custom</quote> fields must consist of
-   nodes that that function can handle.  Furthermore, custom scan providers
+   nodes that function can handle.  Furthermore, custom scan providers
    cannot substitute a larger structure that embeds
    a <structname>CustomScan</structname> for the structure itself, as would be possible
    for a <structname>CustomPath</structname> or <structname>CustomScanState</structname>.
diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml
index 5a709e3d476..c196f6a4a70 100644
--- a/doc/src/sgml/earthdistance.sgml
+++ b/doc/src/sgml/earthdistance.sgml
@@ -32,7 +32,7 @@
  <caution>
   <para>
    It is strongly recommended that <filename>earthdistance</filename>
-   and <filename>cube</filename> be installed in the same schema, and that
+   and <filename>cube</filename> be installed in the same schema, and
    that schema be one for which CREATE privilege has not been and will not
    be granted to any untrusted users.
    Otherwise there are installation-time security hazards
diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 64f8e133cae..31dc821600a 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -461,7 +461,7 @@
      Since there is no way to select a range type knowing only its subtype,
      use of <type>anycompatiblerange</type> and/or
      <type>anycompatiblemultirange</type> requires that all arguments declared
-     with that type have the same actual range and/or multirange type, and that
+     with that type have the same actual range and/or multirange type, and
      that type's subtype agree with the selected common type, so that no casting
      of the range values is required.  As with <type>anyrange</type> and
      <type>anymultirange</type>, use of <type>anycompatiblerange</type> and
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 1c5cfee25d1..d39a3f5aa2b 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -26874,7 +26874,7 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id'));
         syntactically valid type name that happens not to be found in the
         catalogs, the result is <literal>NULL</literal>.  A similar result
         is obtained by casting the string to type <type>regtype</type>
-        (see <xref linkend="datatype-oid"/>), except that that will throw
+        (see <xref linkend="datatype-oid"/>), except that will throw
         error for name not found.
        </para></entry>
       </row>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 077bcc20759..03811cf8d36 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -3642,7 +3642,7 @@ xcrun --show-sdk-path
 ./configure ... PG_SYSROOT=none
 </programlisting>
     (any nonexistent pathname will work).  This might be useful if you wish
-    to build with a non-Apple compiler, but beware that that case is not
+    to build with a non-Apple compiler, but beware that case is not
     tested or supported by the PostgreSQL developers.
    </para>
 
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 3be66789ba7..bafb288f752 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -8455,7 +8455,7 @@ defaultNoticeProcessor(void *arg, const char *message)
 
   <para>
    Once you have set a notice receiver or processor, you should expect
-   that that function could be called as long as either the
+   that function could be called as long as either the
    <structname>PGconn</structname> object or <structname>PGresult</structname> objects made
    from it exist.  At creation of a <structname>PGresult</structname>, the
    <structname>PGconn</structname>'s current notice handling pointers are copied
@@ -8476,7 +8476,7 @@ defaultNoticeProcessor(void *arg, const char *message)
    <structname>PGresult</structname> objects.  A principal use case is that
    this allows applications to associate their own data with a
    <structname>PGconn</structname> or <structname>PGresult</structname>
-   and ensure that that data is freed at an appropriate time.
+   and ensure that data is freed at an appropriate time.
   </para>
 
   <para>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 106583fb296..d3781c77ad9 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -2131,7 +2131,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
      <footnote>
       <para>
        You can get the effect of disabling foreign keys by using
-       the <option>--disable-triggers</option> option &mdash; but realize that
+       the <option>--disable-triggers</option> option &mdash; but realize
        that eliminates, rather than just postpones, foreign key
        validation, and so it is possible to insert bad data if you use it.
       </para>
diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml
index d08834ac9d2..f2124942328 100644
--- a/doc/src/sgml/ref/create_foreign_table.sgml
+++ b/doc/src/sgml/ref/create_foreign_table.sgml
@@ -487,7 +487,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      When a foreign table is used as a partition of a partitioned table,
      there is an implicit constraint that its contents must satisfy the
      partitioning rule.  Again, it is the user's responsibility to ensure
-     that that is true, which is best done by installing a matching
+     that is true, which is best done by installing a matching
      constraint on the remote server.
     </para>
    </caution>
@@ -500,7 +500,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
     However, it is not currently possible to move a row from a
     foreign-table partition to another partition.
     An <command>UPDATE</command> that would require doing that will fail
-    due to the partitioning constraint, assuming that that is properly
+    due to the partitioning constraint, assuming that is properly
     enforced by the remote server.
    </para>
 
diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml
index fd6ed54e8f9..d9bcec59047 100644
--- a/doc/src/sgml/ref/notify.sgml
+++ b/doc/src/sgml/ref/notify.sgml
@@ -113,7 +113,7 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla
    it will get back a notification event, just like all the other
    listening sessions.  Depending on the application logic, this could
    result in useless work, for example, reading a database table to
-   find the same updates that that session just wrote out.  It is
+   find the same updates that session just wrote out.  It is
    possible to avoid such extra work by noticing whether the notifying
    session's server process <acronym>PID</acronym> (supplied in the
    notification event message) is the same as one's own session's
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index df13365b287..7d1d3dceb27 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -1074,7 +1074,7 @@ psql --username=postgres --file=script.sql postgres
    working directory.  In some situations the path name for the current
    directory might be too long to be a valid socket name.  In that case you
    can use the <option>-s</option> option to put the socket files in some
-   directory with a shorter path name.  For security, be sure that that
+   directory with a shorter path name.  For security, be sure that
    directory is not readable or writable by any other users.
    (This is not supported on Windows.)
   </para>
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index b13a16a117f..955be63a60b 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -629,7 +629,7 @@ PostgreSQL documentation
 
    <para>
     A failure message indicating inability to bind to a port might
-    indicate that that port is already in use by some
+    indicate that port is already in use by some
     non-<productname>PostgreSQL</productname> process.  You might also
     get this error if you terminate <command>postgres</command>
     and immediately restart it using the same port; in this case, you
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index bf4ffb30576..7776a67d947 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -662,7 +662,7 @@ result is violating.  However, please report it anyway, so that we can add an
 
     <para>
 You might wonder why we don't order all the regression test queries explicitly
-to get rid of this issue once and for all.  The reason is that that would
+to get rid of this issue once and for all.  The reason is that would
 make the regression tests less useful, not more, since they'd tend
 to exercise query plan types that produce ordered results to the
 exclusion of those that don't.
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 0263a700591..1d71b34075a 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -228,7 +228,7 @@ createdb: error: database creation failed: ERROR:  permission denied to create d
       operating system account.  As it happens, there will always be a
       <productname>PostgreSQL</productname> user account that has the
       same name as the operating system user that started the server,
-      and it also happens that that user always has permission to
+      and it also happens that user always has permission to
       create databases.  Instead of logging in as that user you can
       also specify the <option>-U</option> option everywhere to select
       a <productname>PostgreSQL</productname> user name to connect as.
diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml
index bdad8d3dc2b..f7a8e47d776 100644
--- a/doc/src/sgml/xaggr.sgml
+++ b/doc/src/sgml/xaggr.sgml
@@ -568,7 +568,7 @@ SELECT percentile_disc(0.5) WITHIN GROUP (ORDER BY income) FROM households;
    happens to take a value of the state type, not of the underlying input
    type, as its second argument.  In particular, the rules for dealing
    with null values and strict functions are similar.  Also, if the aggregate
-   definition specifies a non-null <literal>initcond</literal>, keep in mind that
+   definition specifies a non-null <literal>initcond</literal>, keep in mind
    that will be used not only as the initial state for each partial
    aggregation run, but also as the initial state for the combine function,
    which will be called to combine each partial result into that state.
toto.difftext/x-patch; charset=US-ASCII; name=toto.diffDownload
diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index d3145318b36..37271f9c9d0 100644
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -248,7 +248,7 @@ PostgreSQL documentation
       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
       <listitem>
        <para>
-        Specifies the name of the database to connect to to discover which
+        Specifies the name of the database to connect to discover which
         databases should be clustered,
         when <option>-a</option>/<option>--all</option> is used.
         If not specified, the <literal>postgres</literal> database will be used,
diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml
index 98c3333228f..e0407b2bcd5 100644
--- a/doc/src/sgml/ref/reindexdb.sgml
+++ b/doc/src/sgml/ref/reindexdb.sgml
@@ -352,7 +352,7 @@ PostgreSQL documentation
       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
       <listitem>
        <para>
-        Specifies the name of the database to connect to to discover which
+        Specifies the name of the database to connect to discover which
         databases should be reindexed,
         when <option>-a</option>/<option>--all</option> is used.
         If not specified, the <literal>postgres</literal> database will be used,
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index d102f9d4840..b279b4aa4d4 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -560,7 +560,7 @@ PostgreSQL documentation
       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
       <listitem>
        <para>
-        Specifies the name of the database to connect to to discover which
+        Specifies the name of the database to connect to discover which
         databases should be vacuumed,
         when <option>-a</option>/<option>--all</option> is used.
         If not specified, the <literal>postgres</literal> database will be used,
blankline.difftext/x-patch; charset=US-ASCII; name=blankline.diffDownload
diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 1c4ae38f1b9..3f2bcd45a1e 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -898,7 +898,6 @@ typedef void (*LogicalDecodeMessageCB) (struct LogicalDecodingContext *ctx,
       callback might also error out due to simultaneous rollback of
       this very same transaction. In that case, the logical decoding of this
       aborted transaction is stopped gracefully.
-
       The <parameter>prefix</parameter> is arbitrary null-terminated prefix
       which can be used for identifying interesting messages for the current
       plugin. And finally the <parameter>message</parameter> parameter holds
comma.difftext/x-patch; charset=US-ASCII; name=comma.diffDownload
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index c421d89edff..d768ea065c5 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1156,7 +1156,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
    <note>
     <para>
      Extensions can add <literal>Extension</literal>,
-     <literal>InjectionPoint</literal>. and <literal>LWLock</literal> events
+     <literal>InjectionPoint</literal>, and <literal>LWLock</literal> events
      to the lists shown in <xref linkend="wait-event-extension-table"/> and
      <xref linkend="wait-event-lwlock-table"/>. In some cases, the name
      of an <literal>LWLock</literal> assigned by an extension will not be
#2David Rowley
dgrowleyml@gmail.com
In reply to: Noboru Saito (#1)
Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

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]https://english.stackexchange.com/questions/492349/is-my-use-of-that-that-in-this-sentence-gramaticaly-correct 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

#3Noboru Saito
noborusai@gmail.com
In reply to: David Rowley (#2)
Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

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>:

Show quoted text

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

#4David Rowley
dgrowleyml@gmail.com
In reply to: Noboru Saito (#3)
2 attachment(s)
Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

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

Attachments:

app-clusterdb.htmltext/html; charset=UTF-8; name=app-clusterdb.htmlDownload
doc_maintenance-db_improvements.patchapplication/octet-stream; name=doc_maintenance-db_improvements.patchDownload
diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index d3145318b36..0d2051bf6f1 100644
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -248,9 +248,8 @@ PostgreSQL documentation
       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
       <listitem>
        <para>
-        Specifies the name of the database to connect to to discover which
-        databases should be clustered,
-        when <option>-a</option>/<option>--all</option> is used.
+        When the <option>-a</option>/<option>--all</option> is used, connect
+        to this database to gather the list of databases to cluster.
         If not specified, the <literal>postgres</literal> database will be used,
         or if that does not exist, <literal>template1</literal> will be used.
         This can be a <link linkend="libpq-connstring">connection
diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml
index 98c3333228f..abcb041179b 100644
--- a/doc/src/sgml/ref/reindexdb.sgml
+++ b/doc/src/sgml/ref/reindexdb.sgml
@@ -352,9 +352,8 @@ PostgreSQL documentation
       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
       <listitem>
        <para>
-        Specifies the name of the database to connect to to discover which
-        databases should be reindexed,
-        when <option>-a</option>/<option>--all</option> is used.
+        When the <option>-a</option>/<option>--all</option> is used, connect
+        to this database to gather the list of databases to reindex.
         If not specified, the <literal>postgres</literal> database will be used,
         or if that does not exist, <literal>template1</literal> will be used.
         This can be a <link linkend="libpq-connstring">connection
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index d102f9d4840..b0680a61814 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -560,9 +560,8 @@ PostgreSQL documentation
       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
       <listitem>
        <para>
-        Specifies the name of the database to connect to to discover which
-        databases should be vacuumed,
-        when <option>-a</option>/<option>--all</option> is used.
+        When the <option>-a</option>/<option>--all</option> is used, connect
+        to this database to gather the list of databases to vacuum.
         If not specified, the <literal>postgres</literal> database will be used,
         or if that does not exist, <literal>template1</literal> will be used.
         This can be a <link linkend="libpq-connstring">connection
#5David G. Johnston
david.g.johnston@gmail.com
In reply to: David Rowley (#4)
Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

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.

#6David Rowley
dgrowleyml@gmail.com
In reply to: David G. Johnston (#5)
Re: [PATCH] Documentation: Fix minor grammatical and formatting issues

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