Re: PG 14 release notes, first draft

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 (&lt;@ and @&gt;) 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>
       &lt;&lt;| and |&gt;&gt; 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  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  If only the physical world exists, free will is an illusion.