Change locktype "speculative token" to "spectoken".

It's just weird that this name wasn't chosen to look like an
identifier.  The suspicion that it wasn't thought about too
hard is reinforced by the fact that it wasn't documented in
the pg_locks view (until I did so, a day or two back).

Update, and add a comment reminding future adjusters of this
array to fix the docs too.

Do some desultory wordsmithing on various entries in the wait
events tables.

Discussion: https://postgr.es/m/24595.1589326879@sss.pgh.pa.us

2 files changed, 47 insertions, 48 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 9d8fa0bec3f..b1b077c97f8 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -10238,7 +10238,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        <literal>tuple</literal>,
        <literal>transactionid</literal>,
        <literal>virtualxid</literal>,
-       <literal>speculative token</literal>,
+       <literal>spectoken</literal>,
        <literal>object</literal>,
        <literal>userlock</literal>, or
        <literal>advisory</literal>.
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 42755659e1b..be31ac48b13 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -919,68 +919,66 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
     <tbody>
      <row>
       <entry><literal>Activity</literal></entry>
-      <entry>The server process is idle.  This is used by
-       system processes waiting for activity in their main processing loop.
-       <literal>wait_event</literal> will identify the specific wait point.
-       See <xref linkend="wait-event-activity-table"/>.
+      <entry>The server process is idle.  This event type indicates a process
+       waiting for activity in its main processing loop.
+       <literal>wait_event</literal> will identify the specific wait point;
+       see <xref linkend="wait-event-activity-table"/>.
       </entry>
      </row>
      <row>
       <entry><literal>BufferPin</literal></entry>
-      <entry>The server process is waiting to access to
-       a data buffer during a period when no other process can be
-       examining that buffer.  Buffer pin waits can be protracted if
-       another process holds an open cursor which last read data from the
+      <entry>The server process is waiting for exclusive access to
+       a data buffer.  Buffer pin waits can be protracted if
+       another process holds an open cursor that last read data from the
        buffer in question. See <xref linkend="wait-event-bufferpin-table"/>.
       </entry>
      </row>
      <row>
       <entry><literal>Client</literal></entry>
-      <entry>The server process is waiting for some activity
-       on a socket from user applications, and that the server expects
-       something to happen that is independent from its internal processes.
-       <literal>wait_event</literal> will identify the specific wait point.
-       See <xref linkend="wait-event-client-table"/>.
+      <entry>The server process is waiting for activity on a socket
+       connected to a user application.  Thus, the server expects something
+       to happen that is independent of its internal processes.
+       <literal>wait_event</literal> will identify the specific wait point;
+       see <xref linkend="wait-event-client-table"/>.
       </entry>
      </row>
      <row>
       <entry><literal>Extension</literal></entry>
-      <entry>The server process is waiting for activity
-       in an extension module.  This category is useful for modules to
-       track custom waiting points.
+      <entry>The server process is waiting for some condition defined by an
+       extension module.
        See <xref linkend="wait-event-extension-table"/>.
       </entry>
      </row>
      <row>
       <entry><literal>IO</literal></entry>
-      <entry>The server process is waiting for a IO to complete.
-       <literal>wait_event</literal> will identify the specific wait point.
-       See <xref linkend="wait-event-io-table"/>.
+      <entry>The server process is waiting for an I/O operation to complete.
+       <literal>wait_event</literal> will identify the specific wait point;
+       see <xref linkend="wait-event-io-table"/>.
       </entry>
      </row>
      <row>
       <entry><literal>IPC</literal></entry>
-      <entry>The server process is waiting for some activity
-       from another process in the server.  <literal>wait_event</literal> will
-       identify the specific wait point.
-       See <xref linkend="wait-event-ipc-table"/>.
+      <entry>The server process is waiting for some interaction with
+       another server process.  <literal>wait_event</literal> will
+       identify the specific wait point;
+       see <xref linkend="wait-event-ipc-table"/>.
       </entry>
      </row>
      <row>
       <entry><literal>Lock</literal></entry>
-      <entry>The backend is waiting for a heavyweight lock.
+      <entry>The server process is waiting for a heavyweight lock.
        Heavyweight locks, also known as lock manager locks or simply locks,
        primarily protect SQL-visible objects such as tables.  However,
        they are also used to ensure mutual exclusion for certain internal
        operations such as relation extension.  <literal>wait_event</literal>
-       will identify the type of lock awaited.
-       See <xref linkend="wait-event-lock-table"/>.
+       will identify the type of lock awaited;
+       see <xref linkend="wait-event-lock-table"/>.
       </entry>
      </row>
      <row>
       <entry><literal>LWLock</literal></entry>
-      <entry> The backend is waiting for a lightweight lock.
-       Each such lock protects a particular data structure in shared memory.
+      <entry> The server process is waiting for a lightweight lock.
+       Most such locks protect a particular data structure in shared memory.
        <literal>wait_event</literal> will contain a name identifying the purpose
        of the lightweight lock.  (Some locks have specific names; others
        are part of a group of locks each with a similar purpose.)
@@ -991,7 +989,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
       <entry><literal>Timeout</literal></entry>
       <entry>The server process is waiting for a timeout
        to expire.  <literal>wait_event</literal> will identify the specific wait
-       point.  See <xref linkend="wait-event-timeout-table"/>.
+       point; see <xref linkend="wait-event-timeout-table"/>.
       </entry>
      </row>
     </tbody>
@@ -1011,7 +1009,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
     <tbody>
      <row>
       <entry><literal>ArchiverMain</literal></entry>
-      <entry>Waiting in main loop of the archiver process.</entry>
+      <entry>Waiting in main loop of archiver process.</entry>
      </row>
      <row>
       <entry><literal>AutoVacuumMain</literal></entry>
@@ -1023,8 +1021,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      </row>
      <row>
       <entry><literal>BgWriterMain</literal></entry>
-      <entry>Waiting in main loop of background writer process background
-       worker.</entry>
+      <entry>Waiting in main loop of background writer process.</entry>
      </row>
      <row>
       <entry><literal>CheckpointerMain</literal></entry>
@@ -1032,19 +1029,20 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      </row>
      <row>
       <entry><literal>LogicalApplyMain</literal></entry>
-      <entry>Waiting in main loop of logical apply process.</entry>
+      <entry>Waiting in main loop of logical replication apply process.</entry>
      </row>
      <row>
       <entry><literal>LogicalLauncherMain</literal></entry>
-      <entry>Waiting in main loop of logical launcher process.</entry>
+      <entry>Waiting in main loop of logical replication launcher process.</entry>
      </row>
      <row>
       <entry><literal>PgStatMain</literal></entry>
-      <entry>Waiting in main loop of the statistics collector process.</entry>
+      <entry>Waiting in main loop of statistics collector process.</entry>
      </row>
      <row>
       <entry><literal>RecoveryWalStream</literal></entry>
-      <entry>Waiting for WAL from a stream at recovery.</entry>
+      <entry>Waiting in main loop of startup process for WAL to arrive, during
+       streaming recovery.</entry>
      </row>
      <row>
       <entry><literal>SysLoggerMain</literal></entry>
@@ -1079,7 +1077,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
     <tbody>
      <row>
       <entry><literal>BufferPin</literal></entry>
-      <entry>Waiting to acquire a pin on a buffer.</entry>
+      <entry>Waiting to acquire an exclusive pin on a buffer.</entry>
      </row>
     </tbody>
    </tgroup>
@@ -1106,7 +1104,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      </row>
      <row>
       <entry><literal>GSSOpenServer</literal></entry>
-      <entry>Waiting to read data from the client while establishing the GSSAPI
+      <entry>Waiting to read data from the client while establishing a GSSAPI
        session.</entry>
      </row>
      <row>
@@ -1708,14 +1706,14 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      </row>
      <row>
       <entry><literal>page</literal></entry>
-      <entry>Waiting to acquire a lock on page of a relation.</entry>
+      <entry>Waiting to acquire a lock on a page of a relation.</entry>
      </row>
      <row>
       <entry><literal>relation</literal></entry>
       <entry>Waiting to acquire a lock on a relation.</entry>
      </row>
      <row>
-      <entry><literal>speculative token</literal></entry>
+      <entry><literal>spectoken</literal></entry>
       <entry>Waiting to acquire a speculative insertion lock.</entry>
      </row>
      <row>
@@ -1732,7 +1730,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      </row>
      <row>
       <entry><literal>virtualxid</literal></entry>
-      <entry>Waiting to acquire a virtual xid lock.</entry>
+      <entry>Waiting to acquire a virtual transaction ID lock.</entry>
      </row>
     </tbody>
    </tgroup>
@@ -2072,7 +2070,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      Extensions can add <literal>LWLock</literal> types to the list shown in
      <xref linkend="wait-event-lwlock-table"/>.  In some cases, the name
      assigned by an extension will not be available in all server processes;
-     so a wait event might be reported as
+     so an <literal>LWLock</literal> wait event might be reported as
      just <quote><literal>extension</literal></quote> rather than the
      extension-assigned name.
     </para>
@@ -2095,17 +2093,18 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      </row>
      <row>
       <entry><literal>PgSleep</literal></entry>
-      <entry>Waiting in process that called <function>pg_sleep</function>.</entry>
+      <entry>Waiting due to a call to <function>pg_sleep</function> or
+       a sibling function.</entry>
      </row>
      <row>
       <entry><literal>RecoveryApplyDelay</literal></entry>
-      <entry>Waiting to apply WAL at recovery because it is delayed.</entry>
+      <entry>Waiting to apply WAL during recovery because of a delay
+       setting.</entry>
      </row>
      <row>
       <entry><literal>RecoveryRetrieveRetryInterval</literal></entry>
-      <entry>Waiting when WAL data is not available from any kind of sources
-       (<filename>pg_wal</filename>, archive or stream) before trying
-       again to retrieve WAL data, at recovery.</entry>
+      <entry>Waiting during recovery when WAL data is not available from any
+       source (<filename>pg_wal</filename>, archive or stream).</entry>
      </row>
      <row>
       <entry><literal>VacuumDelay</literal></entry>