On Fri, Jun 25, 2021 at 06:04:56PM -0500, Justin Pryzby wrote:
> > Require custom server variable names to use only character which are valid
> > for unquoted SQL identifiers (Tom Lane)
>
> characters plural (since 69a58bfe4)
Fixed.
> > This is similar to how Unicode can be specified in literal string.
>
> literal strings
Fixed.
> > Add executor method to cache results from the inner-side of nested loop
> > joins (David Rowley)
> > This is useful if only a small percentage of rows is checked on the inner
> > side.
>
> I think this should mention the GUC, whether we leave it enabled by default
> (in
> which case people may want to disable it) or disable by default (in which case
> people may want to enable it).
OK, I changed it to:
This is useful if only a small percentage of rows is checked on
the inner side and is controlled by <xref
linkend="guc-enable-resultcache"/>.
> > The postgres_fdw supports these type of scans if async_capable is set.
> this type
> remove "The" ?
New text is:
<link
linkend="postgres-fdw"><application>postgres_fdw</application></link>
supports these type of scans if <literal>async_capable</literal>
I kept "these types" because the paragraph above says:
Allow a query referencing multiple <link
linkend="sql-createforeigntable">foreign tables</link> to perform
foreign table scans in parallel (Robert Haas, Kyotaro Horiguchi,
Thomas Munro, Etsuro Fujita)
so we are talking about scans in parallel, so I think it is plural. Wrong?
> > Prevent the containment operators (<@ and @>) for intarray from using GiST
> > indexes (Tom Lane)
I show this markup as:
Prevent the containment operators (<@ and @>) for <xref
linkend="intarray"/> from using GiST indexes (Tom Lane)
What markup is missing?
> > Remove deprecated containment operators @ and ~ for built-in geometric data
> > types and contrib modules cube, hstore, intarray, and seg (Justin Pryzby)
Same. what is missing?
Remove deprecated containment operators @ and ~ for built-in
<link linkend="functions-geometry">geometric data types</link> and
contrib modules <xref linkend="cube"/>, <xref linkend="hstore"/>,
<xref linkend="intarray"/>, and <xref linkend="seg"/> (Justin Pryzby)
I could link to our "Geometric Functions and Operators" section, but my
understanding is those are operators for our built-in types, not for
extensions, which is what we are talking about here.
> > For example, disregard ^ in its expansion in \1 in (^\d+).*\1.
Fixed:
Improve handling of regular expression <link
linkend="posix-escape-sequences">back-references</link> (Tom Lane)
I didn't know we had a good section for that, but I see it now.
> > Add point operators <<| and |>> to be strictly above/below geometry (Emre
> > Hasegeli)
> > Previously >^ and <^ were marked as performing this test, but non-point
> > geometric operators used these operators for non-strict comparisons,
> > leading to confusion. The old operators still exist but will be eventually
> > removed. ACCURATE?
I see markup on this:
Add <link linkend="functions-geometry">point operators</link>
<<| and |>> to be strictly above/below geometry
(Emre Hasegeli)
> Should these have markup added?
>
> > Certain discarded tokens, like underscore, caused the output of these
> > functions to produce incorrect tsquery output, e.g., both
> > websearch_to_tsquery('"pg_class pg"') and to_tsquery('pg_class <-> pg')
> > used to output '( pg & class ) <-> pg', but now both output 'pg <-> class
> > <-> pg'.
> > Previously, quoted text that contained multiple adjacent discarded tokens
> > were treated as multiple tokens, causing incorrect tsquery output, e.g.,
> > websearch_to_tsquery('"aaa: bbb"') used to output 'aaa <2> bbb', but now
> > outputs 'aaa <-> bbb'.
>
> Missing markup?
I see markup on the main text of this item:
Fix <link
linkend="functions-textsearch"><function>to_tsquery()</function></link>
and <function>websearch_to_tsquery()</function> to properly parse
query text containing discarded tokens (Alexander Korotkov)
> > This is controlled by server variable ssl_crl_dir and libpq connection
> > option sslcrldir. Previously only CRL files could be specified.
OK, added link to sslcrldir.
> > Allow pgstattuple_approx() to report on TOAST tables (Peter Eisentraut)
Fixed:
Allow <link
linkend="pgstattuple"><function>pgstattuple_approx()</function></link>
to report on <acronym>TOAST</acronym> tables (Peter Eisentraut)
> > Add pg_stat_statements_info system view to show pg_stat_statements activity
> > (Katsuragi Yuta, Yuki Seino, Naoki Nakamichi)
The section heading already has a link so I don't add any for individual
items.
> > Add postgres_fdw function postgres_fdw_get_connections() to report open
> > foreign server connections (Bharath Rupireddy)
Same, this is already in the section with a link in the heading.
> > Add primary keys, unique constraints, and foreign keys to system catalogs
> > (Peter Eisentraut)
>
> Should mention and link to pg_get_catalog_foreign_keys()
Uh, why? I don't see the release notes as a place to explain how to use
Postgres features.
> > Pass doubled quote marks in Chapter 36 SQL command strings literally (Tom
> > Lane)
>
> "Chapter 36" looks funny?
> See also: 4f7d1c309
Yes, fixed.
> >Previously window frame clauses like 'inf' PRECEDING AND 'inf' FOLLOWING
> >returned incorrect results.
> >Negative values produced undesirable results.
> >Previously such cases returned 1.
> >This previously was allowed but produced incorrect results.
> >This could be accomplished previously using existing syntax.
>
> All these details could be omitted.
I think explaining the previous behavior helps people understand the new
behavior.
> >Only the target table can be referenced.
>
> Could be omitted or folded into the preceding line.
I only use a single sentence for the main text.
> > This was already disabled by default in previous Postgres releases, and
> > most modern OpenSSL and TLS versions no longer support it.
> > This was last used as the default in Postgres 7.3 (year 2002).
> > By default, Postgres opens and fsyncs every data file at the start of crash
> > recovery. This new setting, recovery_init_sync_method=syncfs, instead syncs
> > each filesystem used by the database cluster. This allows for faster
> > recovery on systems with many database files.
> > The new syntax is SUBSTRING(text SIMILAR pattern ESCAPE escapechar). The
> > previous standard syntax was SUBSTRING(text FROM pattern FOR escapechar),
> > and is still supported by Postgres.
>
> These should all say <productname>PostgreSQL</productname>
OK, fixed.
> > Allow psql's \df and \do commands to specify function and operator argument
> > types (Greg Sabino Mullane, Tom Lane)
> > Add an access method column to psql's \d[i|m|t]+ output (Georgios Kokolatos)
I don't think this one is actually literal.
> > Allow psql's \dt and \di to show TOAST tables and their indexes (Justin
> > Pryzby)
> > Add psql command \dX to list extended statistics objects (Tatsuro Yamada)
> > Fix psql's \dT to understand array syntax and backend grammar aliases, like
> > "int" for "integer" (Greg Sabino Mullane, Tom Lane)
> > When editing the previous query or a file with psql's \e, or using \ef and
> > \ev, ignore the contents if the editor exits without saving (Laurenz Albe)
>
> All these slash commands should be <literal>
Yes, fixed except for the one mentioned above.
> > Stop pg_upgrade from creating analyze_new_cluster script (Michael Paquier)
>
> It's called analyze_new_cluster.sh (except on window), and it's Magnus' patch.
Ah, yes, Magnus, fixed. I don't see the value in adding .sh since it is
not always accurate, but I could add .sh/.bat, but that seems confusing.
> > EXTRACT(date) now throws an error for units that are not part of the date
> > data type.
>
> "Date data" always seems hard to read.
> Could you add markup for "<type>date</type>" ?
Done.
Thank you for all the help on this. Patch attached. Since we just
branched for PG 15, our official developer doc build no longer has the
PG 14 release notes, so I changed my local doc tree to build PG 14 until
PG14 is released in a few months; my URL is:
https://momjian.us/pgsql_docs/release-14.html
--
Bruce Momjian <br...@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
commit caa0f07d2d
Author: Bruce Momjian <br...@momjian.us>
Date: Mon Jun 28 20:58:47 2021 -0400
doc: Improve PG14 release notes
Mostly markup improvements.
Reported-by: Justin Pryzby
Discussion: https://postgr.es/m/20210625230456.gp29...@telsasoft.com
Backpatch-through: 14 only
diff --git a/doc/src/sgml/release-14.sgml b/doc/src/sgml/release-14.sgml
index 000f4e64c4..ebfe76b8cd 100644
--- a/doc/src/sgml/release-14.sgml
+++ b/doc/src/sgml/release-14.sgml
@@ -194,9 +194,9 @@ Author: Michael Paquier <mich...@paquier.xyz>
</para>
<para>
- This was already disabled by default in previous Postgres releases,
- and most modern OpenSSL and <acronym>TLS</acronym> versions no
- longer support it.
+ This was already disabled by default in previous
+ <productname>PostgreSQL</productname> releases, and most modern
+ OpenSSL and <acronym>TLS</acronym> versions no longer support it.
</para>
</listitem>
@@ -213,7 +213,8 @@ Author: Heikki Linnakangas <heikki.linnakan...@iki.fi>
</para>
<para>
- This was last used as the default in Postgres 7.3 (year 2002).
+ This was last used as the default in
+ <productname>PostgreSQL</productname> 7.3 (year 2002).
</para>
</listitem>
@@ -231,7 +232,7 @@ Author: Peter Eisentraut <pe...@eisentraut.org>
<para>
<function>EXTRACT(date)</function> now throws an error for units
- that are not part of the date data type.
+ that are not part of the <type>date</type> data type.
</para>
</listitem>
@@ -395,7 +396,8 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
-->
<para>
- Improve handling of regular expression back-references (Tom Lane)
+ Improve handling of regular expression <link
+ linkend="posix-escape-sequences">back-references</link> (Tom Lane)
</para>
<para>
@@ -430,7 +432,7 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
<para>
Require <link linkend="runtime-config-custom">custom server
- variable</link> names to use only character which are valid for
+ variable</link> names to use only characters which are valid for
unquoted <acronym>SQL</acronym> identifiers (Tom Lane)
</para>
</listitem>
@@ -481,7 +483,7 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
-->
<para>
- Pass doubled quote marks in <xref linkend="ecpg"/>
+ Pass doubled quote marks in <link linkend="ecpg">ecpg</link>
<acronym>SQL</acronym> command strings literally (Tom Lane)
</para>
@@ -1164,7 +1166,8 @@ Author: David Rowley <drow...@postgresql.org>
<para>
This is useful if only a small percentage of rows is checked on
- the inner side.
+ the inner side and is controlled by <xref
+ linkend="guc-enable-resultcache"/>.
</para>
</listitem>
@@ -1211,7 +1214,7 @@ Author: Etsuro Fujita <efuj...@postgresql.org>
</para>
<para>
- The <link
+ <link
linkend="postgres-fdw"><application>postgres_fdw</application></link>
supports these type of scans if <literal>async_capable</literal>
is set.
@@ -1614,8 +1617,9 @@ Author: Peter Eisentraut <pe...@eisentraut.org>
<para>
This is controlled by server variable <xref
- linkend="guc-ssl-crl-dir"/> and libpq connection option sslcrldir.
- Previously only <acronym>CRL</acronym> files could be specified.
+ linkend="guc-ssl-crl-dir"/> and libpq connection option
+ <xref linkend='libpq-connect-sslcrldir'/>. Previously only
+ <acronym>CRL</acronym> files could be specified.
</para>
</listitem>
@@ -1859,8 +1863,9 @@ Author: Thomas Munro <tmu...@postgresql.org>
</para>
<para>
- By default, Postgres opens and fsyncs every data file
- at the start of crash recovery. This new setting, <xref
+ By default, <productname>PostgreSQL</productname>
+ opens and fsyncs every data file at the
+ start of crash recovery. This new setting, <xref
linkend="guc-recovery-init-sync-method"/><literal>=syncfs</literal>,
instead syncs each filesystem used by the database cluster.
This allows for faster recovery on systems with many database files.
@@ -2784,7 +2789,7 @@ Author: Peter Eisentraut <pe...@eisentraut.org>
</para>
<para>
- This is similar to how Unicode can be specified in literal string.
+ This is similar to how Unicode can be specified in literal strings.
</para>
</listitem>
@@ -2868,7 +2873,7 @@ Author: Peter Eisentraut <pe...@eisentraut.org>
The new syntax is <literal>SUBSTRING(text SIMILAR pattern ESCAPE
escapechar)</literal>. The previous standard syntax was
<literal>SUBSTRING(text FROM pattern FOR escapechar)</literal>,
- and is still supported by Postgres.
+ and is still supported by <productname>PostgreSQL</productname>.
</para>
</listitem>
@@ -2894,7 +2899,7 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
<para>
Add <link
linkend="posix-escape-sequences"><literal>[[:word:]]</literal></link>
- as a character class to match \w (Tom Lane)
+ as a character class to match <literal>\w</literal> (Tom Lane)
</para>
</listitem>
@@ -3223,9 +3228,9 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
-->
<para>
- Allow <application>psql</application>'s \df and \do commands to
- specify function and operator argument types (Greg Sabino Mullane,
- Tom Lane)
+ Allow <application>psql</application>'s <literal>\df</literal>
+ and <literal>\do</literal> commands to specify function and
+ operator argument types (Greg Sabino Mullane, Tom Lane)
</para>
<para>
@@ -3252,8 +3257,9 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
-->
<para>
- Allow <application>psql</application>'s \dt and \di to show
- <acronym>TOAST</acronym> tables and their indexes (Justin Pryzby)
+ Allow <application>psql</application>'s <literal>\dt</literal>
+ and <literal>\di</literal> to show <acronym>TOAST</acronym>
+ tables and their indexes (Justin Pryzby)
</para>
</listitem>
@@ -3264,8 +3270,8 @@ Author: Tomas Vondra <tomas.von...@postgresql.org>
-->
<para>
- Add <application>psql</application> command \dX to list extended
- statistics objects (Tatsuro Yamada)
+ Add <application>psql</application> command <literal>\dX</literal>
+ to list extended statistics objects (Tatsuro Yamada)
</para>
</listitem>
@@ -3276,9 +3282,9 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
-->
<para>
- Fix <application>psql</application>'s \dT to understand array
- syntax and backend grammar aliases, like "int" for "integer"
- (Greg Sabino Mullane, Tom Lane)
+ Fix <application>psql</application>'s <literal>\dT</literal> to
+ understand array syntax and backend grammar aliases, like "int"
+ for "integer" (Greg Sabino Mullane, Tom Lane)
</para>
</listitem>
@@ -3290,8 +3296,9 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
<para>
When editing the previous query or a file with
- <application>psql</application>'s \e, or using \ef and \ev, ignore
- the contents if the editor exits without saving (Laurenz Albe)
+ <application>psql</application>'s <literal>\e</literal>, or using
+ <literal>\ef</literal> and <literal>\ev</literal>, ignore the
+ contents if the editor exits without saving (Laurenz Albe)
</para>
<para>
@@ -3306,8 +3313,9 @@ Author: Tom Lane <t...@sss.pgh.pa.us>
-->
<para>
- Improve <application>psql</application>'s handling of \connect
- with <option>-reuse-previous</option> (Tom Lane)
+ Improve <application>psql</application>'s handling of
+ <literal>\connect</literal> with <option>-reuse-previous</option>
+ (Tom Lane)
</para>
<para>
@@ -3414,7 +3422,7 @@ Author: Magnus Hagander <mag...@hagander.net>
Stop <link
linkend="pgupgrade"><application>pg_upgrade</application></link>
from creating <filename>analyze_new_cluster</filename> script
- (Michael Paquier)
+ (Magnus Hagander)
</para>
<para>
@@ -3739,8 +3747,9 @@ Author: Peter Eisentraut <pe...@eisentraut.org>
-->
<para>
- Allow <function>pgstattuple_approx()</function> to report on
- <acronym>TOAST</acronym> tables (Peter Eisentraut)
+ Allow <link
+ linkend="pgstattuple"><function>pgstattuple_approx()</function></link>
+ to report on <acronym>TOAST</acronym> tables (Peter Eisentraut)
</para>
</listitem>
