Re: Probable documentation errors or improvements

On Sat, Sep 19, 2020 at 12:55:58PM -0500, Justin Pryzby wrote:
> On Thu, Sep 10, 2020 at 12:19:55PM -0700, Yaroslav wrote:
> > Disclaimer: I'm not a native speaker, so not sure those are actually
> > incorrect, and can't offer non-trivial suggestions.
>
> https://www.postgresql.org/message-id/flat/CAKFQuwZh3k_CX2-%2BNcZ%3DFZss4bX6ASxDFEXJTY6u4wTH%2BG8%2BKA%40mail.gmail.com#9f9eba0cbbf9b57455503537575f5339
>
> Most of these appear to be reasonable corrections or improvements.
>
> Would you want to submit a patch against the master branch ?
> It'll be easier for people to read when it's in a consistent format.
> And less work to read it than to write it.
>
> I suggest to first handle the 10+ changes which are most important and in need
> of fixing. After a couple rounds, then see if what's left is worth patching.

A couple of these were already fixed (querytree and "be appear").

I provide a patch for a few others.

Copying Teodor et al regarding tsquery.

wdiff to follow.

commit 6c5a4e6fde2841f6a2ad00f3cc4530e7fcf9a9f3
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date: Tue Sep 22 23:34:54 2020 -0500

fix tsquery example

broken since bb140506df605fab58f48926ee1db1f80bdafb59

diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index 8af6ac01d3..7daf292468 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -1623,9 +1623,9 @@ occurrences to display in the result.',

<screen>
SELECT to_tsquery('fat') &lt;-&gt; to_tsquery('cat | rat');
?column?
[-------------------------------------]{+----------------------------+}
'fat' &lt;-&gt; {+(+} 'cat' |[-'fat' &lt;-&gt;-] 'rat' {+)+}
</screen>
</para>
</listitem>

commit 096a9097d58de8e2d21e42fab528b27a5213a699
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date: Tue Sep 22 23:13:00 2020 -0500

HAVING conditions cannot be repeated

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index b93e4ca208..94889b66b4 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -38,7 +38,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replac
[ FROM <replaceable class="parameter">from_item</replaceable> [, ...] ]
[ WHERE <replaceable class="parameter">condition</replaceable> ]
[ GROUP BY <replaceable class="parameter">grouping_element</replaceable> [, ...] ]
[ HAVING <replaceable class="parameter">condition</replaceable>[-[, ...]-] ]
[ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceable class="parameter">window_definition</replaceable> ) [, ...] ]
[ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] <replaceable class="parameter">select</replaceable> ]
[ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]
diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml
index b1af52a4da..e82e416d60 100644
--- a/doc/src/sgml/ref/select_into.sgml
+++ b/doc/src/sgml/ref/select_into.sgml
@@ -28,7 +28,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replac
[ FROM <replaceable class="parameter">from_item</replaceable> [, ...] ]
[ WHERE <replaceable class="parameter">condition</replaceable> ]
[ GROUP BY <replaceable class="parameter">expression</replaceable> [, ...] ]
[ HAVING <replaceable class="parameter">condition</replaceable>[-[, ...]-] ]
[ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceable class="parameter">window_definition</replaceable> ) [, ...] ]
[ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] <replaceable class="parameter">select</replaceable> ]
[ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]

commit 1e16102f906d9ead33ebdfc0b6f5d862e851131b
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date: Tue Sep 22 22:24:14 2020 -0500

style and consistency

diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 390c49eb6a..649020b7da 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -612,7 +612,7 @@ amgettuple (IndexScanDesc scan,
will pass the caller's snapshot test. On success, <function>amgettuple</function>
must also set <literal>scan-&gt;xs_recheck</literal> to true or false.
False means it is certain that the index entry matches the scan keys.
[-true-]{+True+} means this is not certain, and the conditions represented by the
scan keys must be rechecked against the heap tuple after fetching it.
This provision supports <quote>lossy</quote> index operators.
Note that rechecking will extend only to the scan conditions; a partial

commit 44c7efab0499644060c19868d4c431007e8cccaa
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date: Tue Sep 22 22:55:59 2020 -0500

distro agnostic

diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml
index 9961569afc..15417bf19d 100644
--- a/doc/src/sgml/sepgsql.sgml
+++ b/doc/src/sgml/sepgsql.sgml
@@ -88,7 +88,7 @@ Policy from config file: targeted
<para>
To build this module, include the option <literal>--with-selinux</literal> in
your PostgreSQL <literal>configure</literal> command. Be sure that the
<filename>libselinux-devel</filename> [-RPM-]{+package+} is installed at build time.
</para>

<para>
@@ -177,7 +177,7 @@ $ for DBNAME in template0 template1 postgres; do
Makefile on your system; the path shown below is only an example.
(This Makefile is usually supplied by the
<filename>selinux-policy-devel</filename> or
<filename>selinux-policy</filename> [-RPM.)-]{+package.)+}
Once built, install this policy package using the
<command>semodule</command> command, which loads supplied policy packages
into the kernel. If the package is correctly installed,

commit 1584c0dd6a5183b915811c89af08f135479509ab
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date: Tue Sep 22 22:55:48 2020 -0500

grammar

diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index 5c8d4d5275..67754f52f6 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -612,7 +612,7 @@
</para>
<para>
<varname>gin_pending_list_limit</varname> can be overridden for individual
GIN indexes by changing storage parameters,[-and-] which allows each
GIN index to have its own cleanup threshold.
For example, it's possible to increase the threshold only for the GIN
index which can be updated heavily, and decrease it otherwise.
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index beb309e668..a9b7e8fc99 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1503,7 +1503,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
Note that in this mode, the server will apply WAL one file at a
time, so if you use the standby server for queries (see Hot Standby),
there is a delay between an action in the primary and when the
action becomes visible in the standby, corresponding {+to+} the time it takes
to fill up the WAL file. <varname>archive_timeout</varname> can be used to make that delay
shorter. Also note that you can't combine streaming replication with
this method.
diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml
index e55ed07312..709bc8345c 100644
--- a/doc/src/sgml/isn.sgml
+++ b/doc/src/sgml/isn.sgml
@@ -14,7 +14,7 @@
hard-coded list of prefixes; this list of prefixes is also used to hyphenate
numbers on output. Since new prefixes are assigned from time to time, the
list of prefixes may be out of date. It is hoped that a future version of
this module will [-obtained-]{+obtain+} the prefix list from one or more tables that
can be easily updated by users as needed; however, at present, the
list can only be updated by modifying the source code and recompiling.
Alternatively, prefix validation and hyphenation support may be
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 6920913a26..92861e5cfd 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1246,7 +1246,7 @@ ERROR: could not serialize access due to read/write dependencies among transact
<para>
The <literal>FOR UPDATE</literal> lock mode
is also acquired by any <command>DELETE</command> on a row, and also by an
<command>UPDATE</command> that modifies the values [-on-]{+of+} certain columns. Currently,
the set of columns considered for the <command>UPDATE</command> case are those that
have a unique index on them that can be used in a foreign key (so partial
indexes and expressional indexes are not considered), but this may change
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index f5e3318106..06068f87a4 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -2837,7 +2837,7 @@ The commands accepted in replication mode are:
<para>
Every sent transaction contains zero or more DML messages (Insert,
Update, Delete). In case of a cascaded setup it can also contain Origin
messages. The origin message [-indicated-]{+indicates+} that the transaction originated on
different replication node. Since a replication node in the scope of logical
replication protocol can be pretty much anything, the only identifier
is the origin name. It's downstream's responsibility to handle this as
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index 2ebdf02bfa..8af6ac01d3 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -1645,7 +1645,7 @@ SELECT to_tsquery('fat') &lt;-&gt; to_tsquery('cat | rat');
<listitem>
<para>
Returns a query that searches for a match to the first given query
followed by a match to the second given query at a distance of [-at-]{+exactly+}
<replaceable>distance</replaceable> lexemes, using
the <literal>&lt;<replaceable>N</replaceable>&gt;</literal>
<type>tsquery</type> operator. For example:

commit fe18f111c589378eb6bc0ed0ac6f8efb317c25b4
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date: Tue Sep 22 22:48:52 2020 -0500

Avoid ending a sentence about "..." with ".." ..

.. which then looks just the same as "...".

diff --git a/doc/src/sgml/seg.sgml b/doc/src/sgml/seg.sgml
index e86142d885..e0dfbc76cf 100644
--- a/doc/src/sgml/seg.sgml
+++ b/doc/src/sgml/seg.sgml
@@ -205,8 +205,8 @@ test=&gt; select '6.25 .. 6.50'::seg as "pH";
</table>

<para>
Because {+the+} <literal>...</literal> {+operator+} is widely used in data sources, it is allowed
as an alternative spelling of [-<literal>..</literal>.-]{+the <literal>..</literal> operator.+} Unfortunately, this
creates a parsing ambiguity: it is not clear whether the upper bound
in <literal>0...23</literal> is meant to be <literal>23</literal> or <literal>0.23</literal>.
This is resolved by requiring at least one digit before the decimal

commit fabaf97865d46377ed4dbbbb1109299eb037394f
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date: Tue Sep 22 22:51:47 2020 -0500

punctuation

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index de9bacd34f..d1b8fc8010 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1525,7 +1525,7 @@
</para>
<para>
Role can log in. That is, this role can be given as the initial
session authorization [-identifier-]{+identifier.+}
</para></entry>
</row>

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 8eabf93834..1c753ccb7e 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -10084,8 +10084,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
</term>
<listitem>
<para>
If set, do not trace locks for tables below this [-OID. (use-]{+OID (used+} to avoid
output on system [-tables)-]{+tables).+}
</para>
<para>
This parameter is only available if the <symbol>LOCK_DEBUG</symbol>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 461b748d89..8ec58c8577 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -26656,7 +26656,7 @@ BEGIN
RAISE NOTICE 'rewriting table % for reason %',
pg_event_trigger_table_rewrite_oid()::regclass,
pg_event_trigger_table_rewrite_reason();
[-END;-]{+END+}
$$;

CREATE EVENT TRIGGER test_table_rewrite_oid
diff --git a/doc/src/sgml/parallel.sgml b/doc/src/sgml/parallel.sgml
index e31bd9d3ce..c81abff48d 100644
--- a/doc/src/sgml/parallel.sgml
+++ b/doc/src/sgml/parallel.sgml
@@ -471,7 +471,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
</para>

<para>
The following operations are always parallel [-restricted.-]{+restricted:+}
</para>

<itemizedlist>

commit adf050ac6cc7d0905fc1613dce1a04f76a892609
Author: Justin Pryzby <pryzbyj(at)telsasoft(dot)com>
Date: Tue Sep 22 21:40:17 2020 -0500

extraneous comma

diff --git a/doc/src/sgml/rules.sgml b/doc/src/sgml/rules.sgml
index bcf860b68b..d6e3463ac2 100644
--- a/doc/src/sgml/rules.sgml
+++ b/doc/src/sgml/rules.sgml
@@ -769,7 +769,7 @@ SELECT t1.a, t2.b, t1.ctid FROM t1, t2 WHERE t1.a = t2.a;
</para>

<para>
The benefit of implementing views with the rule system [-is,-]{+is+}
that the planner has all
the information about which tables have to be scanned plus the
relationships between these tables plus the restrictive
@@ -781,7 +781,7 @@ SELECT t1.a, t2.b, t1.ctid FROM t1, t2 WHERE t1.a = t2.a;
the best path to execute the query, and the more information
the planner has, the better this decision can be. And
the rule system as implemented in <productname>PostgreSQL</productname>
[-ensures,-]{+ensures+} that this is all information available about the query
up to that point.
</para>
</sect2>