Thread: typos in comments and user docs

typos in comments and user docs

From
Justin Pryzby
Date:
I sent earlier version of this a few times last year along with bunch of other
doc patches but it was never picked up.  So maybe I'll try send one at a time
in more digestible chunks.
https://www.postgresql.org/message-id/flat/20190427025647.GD3925%40telsasoft.com#e1731c33455145eadc1158042cc411f9

From cb5842724330dfcfc914f2e3effdbfe4843be565 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Thu, 9 May 2019 21:13:55 -0500
Subject: [PATCH] spelling and typos

---
 doc/src/sgml/bloom.sgml                    | 2 +-
 doc/src/sgml/config.sgml                   | 2 +-
 doc/src/sgml/ref/alter_table.sgml          | 2 +-
 doc/src/sgml/sources.sgml                  | 4 ++--
 src/backend/access/transam/README.parallel | 2 +-
 src/backend/storage/buffer/bufmgr.c        | 2 +-
 src/backend/storage/sync/sync.c            | 2 +-
 src/include/access/tableam.h               | 2 +-
 8 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml
index 6eeadde..c341b65 100644
--- a/doc/src/sgml/bloom.sgml
+++ b/doc/src/sgml/bloom.sgml
@@ -65,7 +65,7 @@
      <para>
       Number of bits generated for each index column. Each parameter's name
       refers to the number of the index column that it controls.  The default
-      is <literal>2</literal> bits and maximum is <literal>4095</literal>.  Parameters for
+      is <literal>2</literal> bits and the maximum is <literal>4095</literal>.  Parameters for
       index columns not actually used are ignored.
      </para>
     </listitem>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index b2c89bd..102698b 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4318,7 +4318,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
         except crash recovery.
 
         <varname>hot_standby_feedback</varname> will be delayed by use of this feature.
-        Combinining these settings could lead to bloat on the master, so should
+        Combining these settings could lead to bloat on the master, so should
         be done only with care.
 
         <warning>
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 5de3676..a22770c 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -222,7 +222,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
 
      <para>
       <literal>SET NOT NULL</literal> may only be applied to a column
-      providing none of the records in the table contain a
+      provided none of the records in the table contain a
       <literal>NULL</literal> value for the column.  Ordinarily this is
       checked during the <literal>ALTER TABLE</literal> by scanning the
       entire table; however, if a valid <literal>CHECK</literal> constraint is
diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
index 5831ec4..b5d28e7 100644
--- a/doc/src/sgml/sources.sgml
+++ b/doc/src/sgml/sources.sgml
@@ -511,7 +511,7 @@ Hint:       the addendum
 
    <para>
     There are functions in the backend that will double-quote their own output
-    at need (for example, <function>format_type_be()</function>).  Do not put
+    as needed (for example, <function>format_type_be()</function>).  Do not put
     additional quotes around the output of such functions.
    </para>
 
@@ -880,7 +880,7 @@ BETTER: unrecognized node type: 42
      practices.
     </para>
     <para>
-     Features from later revision of the C standard or compiler specific
+     Features from later revisions of the C standard or compiler specific
      features can be used, if a fallback is provided.
     </para>
     <para>
diff --git a/src/backend/access/transam/README.parallel b/src/backend/access/transam/README.parallel
index 85e5840..99c588d 100644
--- a/src/backend/access/transam/README.parallel
+++ b/src/backend/access/transam/README.parallel
@@ -169,7 +169,7 @@ differently because of them.  Right now, we don't even allow that.
 At the end of a parallel operation, which can happen either because it
 completed successfully or because it was interrupted by an error, parallel
 workers associated with that operation exit.  In the error case, transaction
-abort processing in the parallel leader kills of any remaining workers, and
+abort processing in the parallel leader kills off any remaining workers, and
 the parallel leader then waits for them to die.  In the case of a successful
 parallel operation, the parallel leader does not send any signals, but must
 wait for workers to complete and exit of their own volition.  In either
diff --git a/src/backend/storage/buffer/bufmgr.c b/src/backend/storage/buffer/bufmgr.c
index aba3960..5880054 100644
--- a/src/backend/storage/buffer/bufmgr.c
+++ b/src/backend/storage/buffer/bufmgr.c
@@ -4291,7 +4291,7 @@ ts_ckpt_progress_comparator(Datum a, Datum b, void *arg)
  *
  * *max_pending is a pointer instead of an immediate value, so the coalesce
  * limits can easily changed by the GUC mechanism, and so calling code does
- * not have to check the current configuration. A value is 0 means that no
+ * not have to check the current configuration. A value of 0 means that no
  * writeback control will be performed.
  */
 void
diff --git a/src/backend/storage/sync/sync.c b/src/backend/storage/sync/sync.c
index 9cb7c65..8282a47 100644
--- a/src/backend/storage/sync/sync.c
+++ b/src/backend/storage/sync/sync.c
@@ -216,7 +216,7 @@ SyncPostCheckpoint(void)
 
         /*
          * As in ProcessSyncRequests, we don't want to stop absorbing fsync
-         * requests for along time when there are many deletions to be done.
+         * requests for a long time when there are many deletions to be done.
          * We can safely call AbsorbSyncRequests() at this point in the loop
          * (note it might try to delete list entries).
          */
diff --git a/src/include/access/tableam.h b/src/include/access/tableam.h
index 696451f..ba9f7b8 100644
--- a/src/include/access/tableam.h
+++ b/src/include/access/tableam.h
@@ -1185,7 +1185,7 @@ table_tuple_complete_speculative(Relation rel, TupleTableSlot *slot,
  * operation. That's often faster than calling table_insert() in a loop,
  * because e.g. the AM can reduce WAL logging and page locking overhead.
  *
- * Except for taking `nslots` tuples as input, as an array of TupleTableSlots
+ * Except for taking `nslots` tuples as input, and an array of TupleTableSlots
  * in `slots`, the parameters for table_multi_insert() are the same as for
  * table_tuple_insert().
  *
-- 
2.7.4


Attachment

Re: typos in comments and user docs

From
Amit Kapila
Date:
On Thu, Feb 6, 2020 at 7:44 AM Justin Pryzby <pryzby@telsasoft.com> wrote:
>
> I sent earlier version of this a few times last year along with bunch of other
> doc patches but it was never picked up.  So maybe I'll try send one at a time
> in more digestible chunks.
> https://www.postgresql.org/message-id/flat/20190427025647.GD3925%40telsasoft.com#e1731c33455145eadc1158042cc411f9
>
> From cb5842724330dfcfc914f2e3effdbfe4843be565 Mon Sep 17 00:00:00 2001
> From: Justin Pryzby <pryzbyj@telsasoft.com>
> Date: Thu, 9 May 2019 21:13:55 -0500
> Subject: [PATCH] spelling and typos
>
> ---
>  doc/src/sgml/bloom.sgml                    | 2 +-
>  doc/src/sgml/config.sgml                   | 2 +-
>  doc/src/sgml/ref/alter_table.sgml          | 2 +-
>  doc/src/sgml/sources.sgml                  | 4 ++--
>  src/backend/access/transam/README.parallel | 2 +-
>  src/backend/storage/buffer/bufmgr.c        | 2 +-
>  src/backend/storage/sync/sync.c            | 2 +-
>  src/include/access/tableam.h               | 2 +-
>  8 files changed, 9 insertions(+), 9 deletions(-)
>

Your changes look fine to me on the first read.  I will push this to
HEAD unless there are any objections.   If we want them in
back-branches, we might want to probably segregate the changes based
on the branch until those apply.

-- 
With Regards,
Amit Kapila.
EnterpriseDB: http://www.enterprisedb.com



Re: typos in comments and user docs

From
Michael Paquier
Date:
On Thu, Feb 06, 2020 at 08:47:14AM +0530, Amit Kapila wrote:
> Your changes look fine to me on the first read.  I will push this to
> HEAD unless there are any objections.   If we want them in
> back-branches, we might want to probably segregate the changes based
> on the branch until those apply.

+1.  It would be nice to back-patch the user-visible changes in the
docs.
--
Michael

Attachment

Re: typos in comments and user docs

From
Amit Kapila
Date:
On Thu, Feb 6, 2020 at 10:45 AM Michael Paquier <michael@paquier.xyz> wrote:
>
> On Thu, Feb 06, 2020 at 08:47:14AM +0530, Amit Kapila wrote:
> > Your changes look fine to me on the first read.  I will push this to
> > HEAD unless there are any objections.   If we want them in
> > back-branches, we might want to probably segregate the changes based
> > on the branch until those apply.
>
> +1.  It would be nice to back-patch the user-visible changes in the
> docs.
>

Fair enough, Justin, is it possible for you to segregate the changes
that can be backpatched?

-- 
With Regards,
Amit Kapila.
EnterpriseDB: http://www.enterprisedb.com



Re: typos in comments and user docs

From
Justin Pryzby
Date:
On Thu, Feb 06, 2020 at 04:43:18PM +0530, Amit Kapila wrote:
> On Thu, Feb 6, 2020 at 10:45 AM Michael Paquier <michael@paquier.xyz> wrote:
> >
> > On Thu, Feb 06, 2020 at 08:47:14AM +0530, Amit Kapila wrote:
> > > Your changes look fine to me on the first read.  I will push this to
> > > HEAD unless there are any objections.   If we want them in
> > > back-branches, we might want to probably segregate the changes based
> > > on the branch until those apply.
> >
> > +1.  It would be nice to back-patch the user-visible changes in the
> > docs.
> >
> 
> Fair enough, Justin, is it possible for you to segregate the changes
> that can be backpatched?

Looks like the whole patch can be applied to master and v12 [0].

My original thread from last year was about docs added in v12, so bloom.sgml is
the only user-facing doc which can be backpatched.  README.parallel and
bufmgr.c changes could be backpatched but I agree it's not necessary.

Note, the bloom typo seems to complete a change that was started here:

|commit 31ff51adc855e3ffe8e3c20e479b8d1a4508feb8
|Author: Alexander Korotkov <akorotkov@postgresql.org>
|Date:   Mon Oct 22 00:23:26 2018 +0300
|
|    Fix some grammar errors in bloom.sgml
|    
|    Discussion: https://postgr.es/m/CAEepm%3D3sijpGr8tXdyz-7EJJZfhQHABPKEQ29gpnb7-XSy%2B%3D5A%40mail.gmail.com
|    Reported-by: Thomas Munro
|    Backpatch-through: 9.6

Justin

[0] modulo a fix for a typo which I introduced in another patch in this branch,
which shouldn't have been in this patch; fixed in the attached.

Attachment

Re: typos in comments and user docs

From
Amit Kapila
Date:
On Thu, Feb 6, 2020 at 7:26 PM Justin Pryzby <pryzby@telsasoft.com> wrote:
>
> On Thu, Feb 06, 2020 at 04:43:18PM +0530, Amit Kapila wrote:
> > On Thu, Feb 6, 2020 at 10:45 AM Michael Paquier <michael@paquier.xyz> wrote:
> > >
> > > On Thu, Feb 06, 2020 at 08:47:14AM +0530, Amit Kapila wrote:
> > > > Your changes look fine to me on the first read.  I will push this to
> > > > HEAD unless there are any objections.   If we want them in
> > > > back-branches, we might want to probably segregate the changes based
> > > > on the branch until those apply.
> > >
> > > +1.  It would be nice to back-patch the user-visible changes in the
> > > docs.
> > >
> >
> > Fair enough, Justin, is it possible for you to segregate the changes
> > that can be backpatched?
>
> Looks like the whole patch can be applied to master and v12 [0].
>

If we decide to backpatch, then why not try to backpatch as far as
possible (till 9.5)?  If so, then it would be better to separate
changes which can be backpatched till 9.5, if that is tedious, then
maybe we can just back-patch (in 12) bloom.sgml change as a separate
commit and rest commit it in HEAD only.  What do you think?


-- 
With Regards,
Amit Kapila.
EnterpriseDB: http://www.enterprisedb.com



Re: typos in comments and user docs

From
Justin Pryzby
Date:
On Fri, Feb 07, 2020 at 08:33:40AM +0530, Amit Kapila wrote:
> On Thu, Feb 6, 2020 at 7:26 PM Justin Pryzby <pryzby@telsasoft.com> wrote:
> >
> > On Thu, Feb 06, 2020 at 04:43:18PM +0530, Amit Kapila wrote:
> > > On Thu, Feb 6, 2020 at 10:45 AM Michael Paquier <michael@paquier.xyz> wrote:
> > > >
> > > > On Thu, Feb 06, 2020 at 08:47:14AM +0530, Amit Kapila wrote:
> > > > > Your changes look fine to me on the first read.  I will push this to
> > > > > HEAD unless there are any objections.   If we want them in
> > > > > back-branches, we might want to probably segregate the changes based
> > > > > on the branch until those apply.
> > > >
> > > > +1.  It would be nice to back-patch the user-visible changes in the
> > > > docs.
> > > >
> > >
> > > Fair enough, Justin, is it possible for you to segregate the changes
> > > that can be backpatched?
> >
> > Looks like the whole patch can be applied to master and v12 [0].
> 
> If we decide to backpatch, then why not try to backpatch as far as
> possible (till 9.5)?  If so, then it would be better to separate
> changes which can be backpatched till 9.5, if that is tedious, then
> maybe we can just back-patch (in 12) bloom.sgml change as a separate
> commit and rest commit it in HEAD only.  What do you think?

I don't think I was clear.  My original doc review patches were limited to
this:

On Sat, Mar 30, 2019 at 05:43:33PM -0500, Justin Pryzby wrote:
> I reviewed docs like this:
> git log -p remotes/origin/REL_11_STABLE..HEAD -- doc


STABLE..REL_12_STABLE.  So after a few minutes earlier today of cherry-pick, I
concluded that only bloom.sgml is applicable further back than v12.  Probably,
I either noticed that minor issue at the same time as nearby doc changes in
v12(?), or maybe noticed that issue later, independently of doc review, but
then tacked it on to the previous commit, for lack of any better place.

Justin



Re: typos in comments and user docs

From
Amit Kapila
Date:
On Fri, Feb 7, 2020 at 8:41 AM Justin Pryzby <pryzby@telsasoft.com> wrote:
>
> On Fri, Feb 07, 2020 at 08:33:40AM +0530, Amit Kapila wrote:
> > On Thu, Feb 6, 2020 at 7:26 PM Justin Pryzby <pryzby@telsasoft.com> wrote:
> > >
> > > On Thu, Feb 06, 2020 at 04:43:18PM +0530, Amit Kapila wrote:
> > > > On Thu, Feb 6, 2020 at 10:45 AM Michael Paquier <michael@paquier.xyz> wrote:
> > > > >
> > > > > On Thu, Feb 06, 2020 at 08:47:14AM +0530, Amit Kapila wrote:
> > > > > > Your changes look fine to me on the first read.  I will push this to
> > > > > > HEAD unless there are any objections.   If we want them in
> > > > > > back-branches, we might want to probably segregate the changes based
> > > > > > on the branch until those apply.
> > > > >
> > > > > +1.  It would be nice to back-patch the user-visible changes in the
> > > > > docs.
> > > > >
> > > >
> > > > Fair enough, Justin, is it possible for you to segregate the changes
> > > > that can be backpatched?
> > >
> > > Looks like the whole patch can be applied to master and v12 [0].
> >

I tried your patch master and it failed to apply.
(Stripping trailing CRs from patch; use --binary to disable.)
patching file doc/src/sgml/bloom.sgml
(Stripping trailing CRs from patch; use --binary to disable.)
patching file doc/src/sgml/config.sgml
Hunk #1 FAILED at 4318.
1 out of 1 hunk FAILED -- saving rejects to file doc/src/sgml/config.sgml.rej

> > If we decide to backpatch, then why not try to backpatch as far as
> > possible (till 9.5)?  If so, then it would be better to separate
> > changes which can be backpatched till 9.5, if that is tedious, then
> > maybe we can just back-patch (in 12) bloom.sgml change as a separate
> > commit and rest commit it in HEAD only.  What do you think?
>
> I don't think I was clear.  My original doc review patches were limited to
> this:
>
> On Sat, Mar 30, 2019 at 05:43:33PM -0500, Justin Pryzby wrote:
> > I reviewed docs like this:
> > git log -p remotes/origin/REL_11_STABLE..HEAD -- doc
>
>
> STABLE..REL_12_STABLE.  So after a few minutes earlier today of cherry-pick, I
> concluded that only bloom.sgml is applicable further back than v12.  Probably,
> I either noticed that minor issue at the same time as nearby doc changes in
> v12(?), or maybe noticed that issue later, independently of doc review, but
> then tacked it on to the previous commit, for lack of any better place.
>

I am still not 100% clear, it is better if you can prepare a separate
patch which can be backpatched and the rest that we can apply to HEAD.

-- 
With Regards,
Amit Kapila.
EnterpriseDB: http://www.enterprisedb.com



Re: typos in comments and user docs

From
Justin Pryzby
Date:
On Fri, Feb 07, 2020 at 09:26:04AM +0530, Amit Kapila wrote:
> On Fri, Feb 7, 2020 at 8:41 AM Justin Pryzby <pryzby@telsasoft.com> wrote:
> >
> > On Fri, Feb 07, 2020 at 08:33:40AM +0530, Amit Kapila wrote:
> > > On Thu, Feb 6, 2020 at 7:26 PM Justin Pryzby <pryzby@telsasoft.com> wrote:
> > > >
> > > > On Thu, Feb 06, 2020 at 04:43:18PM +0530, Amit Kapila wrote:
> > > > > On Thu, Feb 6, 2020 at 10:45 AM Michael Paquier <michael@paquier.xyz> wrote:
> > > > > >
> > > > > > On Thu, Feb 06, 2020 at 08:47:14AM +0530, Amit Kapila wrote:
> > > > > > > Your changes look fine to me on the first read.  I will push this to
> > > > > > > HEAD unless there are any objections.   If we want them in
> > > > > > > back-branches, we might want to probably segregate the changes based
> > > > > > > on the branch until those apply.
> > > > > >
> > > > > > +1.  It would be nice to back-patch the user-visible changes in the
> > > > > > docs.
> > > > > >
> > > > >
> > > > > Fair enough, Justin, is it possible for you to segregate the changes
> > > > > that can be backpatched?
> > > >
> > > > Looks like the whole patch can be applied to master and v12 [0].
> > >
> 
> I tried your patch master and it failed to apply.
> (Stripping trailing CRs from patch; use --binary to disable.)
> patching file doc/src/sgml/bloom.sgml
> (Stripping trailing CRs from patch; use --binary to disable.)
> patching file doc/src/sgml/config.sgml
> Hunk #1 FAILED at 4318.
> 1 out of 1 hunk FAILED -- saving rejects to file doc/src/sgml/config.sgml.rej

I think you applied the first patch, which I corrected here.
https://www.postgresql.org/message-id/20200206135640.GG403%40telsasoft.com

Just rechecked it works for master and v12.

$ git checkout -b test2  origin/master
Branch test2 set up to track remote branch master from origin.
Switched to a new branch 'test2'
$ patch -p1 <0001-spelling-and-typos.patch
patching file doc/src/sgml/bloom.sgml
patching file doc/src/sgml/ref/alter_table.sgml
patching file doc/src/sgml/sources.sgml
patching file src/backend/access/transam/README.parallel
patching file src/backend/storage/buffer/bufmgr.c
patching file src/backend/storage/sync/sync.c
patching file src/include/access/tableam.h

$ patch -p1 <0001-spelling-and-typos.patch
patching file doc/src/sgml/bloom.sgml
patching file doc/src/sgml/ref/alter_table.sgml
Hunk #1 succeeded at 220 (offset -2 lines).
patching file doc/src/sgml/sources.sgml
patching file src/backend/access/transam/README.parallel
patching file src/backend/storage/buffer/bufmgr.c
Hunk #1 succeeded at 4268 (offset -23 lines).
patching file src/backend/storage/sync/sync.c
patching file src/include/access/tableam.h
Hunk #1 succeeded at 1167 (offset -18 lines).

The bloom patch there works for v11.
Attached now another version for v10-.

Attachment

Re: typos in comments and user docs

From
Amit Kapila
Date:
On Fri, Feb 7, 2020 at 9:47 AM Justin Pryzby <pryzby@telsasoft.com> wrote:
>
> On Fri, Feb 07, 2020 at 09:26:04AM +0530, Amit Kapila wrote:
> > On Fri, Feb 7, 2020 at 8:41 AM Justin Pryzby <pryzby@telsasoft.com> wrote:
> > >
> > > On Fri, Feb 07, 2020 at 08:33:40AM +0530, Amit Kapila wrote:
> > > > On Thu, Feb 6, 2020 at 7:26 PM Justin Pryzby <pryzby@telsasoft.com> wrote:
> > > > >
> > > > > On Thu, Feb 06, 2020 at 04:43:18PM +0530, Amit Kapila wrote:
> > > > > > On Thu, Feb 6, 2020 at 10:45 AM Michael Paquier <michael@paquier.xyz> wrote:
> > > > > > >
> > > > > > > On Thu, Feb 06, 2020 at 08:47:14AM +0530, Amit Kapila wrote:
> > > > > > > > Your changes look fine to me on the first read.  I will push this to
> > > > > > > > HEAD unless there are any objections.   If we want them in
> > > > > > > > back-branches, we might want to probably segregate the changes based
> > > > > > > > on the branch until those apply.
> > > > > > >
> > > > > > > +1.  It would be nice to back-patch the user-visible changes in the
> > > > > > > docs.
> > > > > > >
> > > > > >
> > > > > > Fair enough, Justin, is it possible for you to segregate the changes
> > > > > > that can be backpatched?
> > > > >
> > > > > Looks like the whole patch can be applied to master and v12 [0].
> > > >
> >
> > I tried your patch master and it failed to apply.
> > (Stripping trailing CRs from patch; use --binary to disable.)
> > patching file doc/src/sgml/bloom.sgml
> > (Stripping trailing CRs from patch; use --binary to disable.)
> > patching file doc/src/sgml/config.sgml
> > Hunk #1 FAILED at 4318.
> > 1 out of 1 hunk FAILED -- saving rejects to file doc/src/sgml/config.sgml.rej
>
> I think you applied the first patch, which I corrected here.
> https://www.postgresql.org/message-id/20200206135640.GG403%40telsasoft.com
>
> Just rechecked it works for master and v12.
>

Okay, thanks.  I have pushed user-facing changes (bloom.sgml and
alter_table.sgml) to back branches till they apply and rest of the
changes in just HEAD.

-- 
With Regards,
Amit Kapila.
EnterpriseDB: http://www.enterprisedb.com