Re: [doc] remove reference to pg_dump pre-8.1 switch behaviour

On Sun, Nov 29, 2020 at 01:27:48PM -0600, Justin Pryzby wrote:
> activity of scans already in progress. This can result in
> unpredictable changes in the row ordering returned by queries that
> have no <literal>ORDER BY</literal> clause. Setting this parameter to
> - <literal>off</literal> ensures the pre-8.3 behavior in which a sequential
> + <literal>off</literal> ensures the simple behavior in which a sequential
> scan always starts from the beginning of the table. The default
> is <literal>on</literal>.

Mentioned upthread, but I see no problems in keeping this reference
either.

> (last subscript varies most rapidly).
> If the contents of two arrays are equal but the dimensionality is
> different, the first difference in the dimensionality information
> - determines the sort order. (This is a change from versions of
> - <productname>PostgreSQL</productname> prior to 8.2: older versions would claim
> - that two arrays with the same contents were equal, even if the
> - number of dimensions or subscript ranges were different.)
> + determines the sort order.
> </para>

OK to remove this one. That was +1'd three times upthread. I guess
that it just got missed.

> <replaceable class="parameter">mode</replaceable> is unused and
> - ignored as of <productname>PostgreSQL</productname> 8.1; however, for
> + ignored since <productname>PostgreSQL</productname> 8.1; however, for
> backward compatibility with earlier releases it is best to
> set it to <symbol>INV_READ</symbol>, <symbol>INV_WRITE</symbol>,
> or <symbol>INV_READ</symbol> <literal>|</literal> <symbol>INV_WRITE</symbol>

Don't see a point in changing that. I don't agree with just removing
the parameter either as that may just break stuff.

> Data of a particular data type might be transmitted in any of several
> - different <firstterm>formats</firstterm>. As of <productname>PostgreSQL</productname> 7.4
> + different <firstterm>formats</firstterm>. Currently
> the only supported formats are <quote>text</quote> and <quote>binary</quote>,
> but the protocol makes provision for future extensions. The desired
> format for any value is specified by a <firstterm>format code</firstterm>.

Don't think there was an agreement on that.

> - <para>
> - The syntax
> -<synopsis>
> -CLUSTER <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
> -</synopsis>
> - is also supported for compatibility with pre-8.3 <productname>PostgreSQL</productname>
> - versions.
> - </para>
> </refsect1>
>
> <refsect1>

Seems to me that this should be kept for now.

> - Before <productname>PostgreSQL</productname> 8.3, these functions would
> - silently accept values of several non-string data types as well, due to
> - the presence of implicit coercions from those data types to
> - <type>text</type>. Those coercions have been removed because they frequently
> - caused surprising behaviors. However, the string concatenation operator
> - (<literal>||</literal>) still accepts non-string input, so long as at least one
> - input is of a string type, as shown in <xref
> - linkend="functions-string-sql"/>. For other cases, insert an explicit
> - coercion to <type>text</type> if you need to duplicate the previous behavior.
> + The string concatenation operator (<literal>||</literal>) will accept
> + non-string input, so long as at least one input is of string type, as shown
> + in <xref linkend="functions-string-sql"/>. For other cases, inserting an
> + explicit coercion to <type>text</type> can be used to have non-string input
> + accepted.
> </para>
> </note>

Word-by-word what Stephen has written upthread. Agreed that this is
an improvement.

> + Building a <acronym>GIN</acronym> index after all of the data has been
> + loaded will typically be faster than creating the index and then filling
> + it. There may also be cases where, for a sufficiently large update,
> + dropping the <acronym>GIN</acronym> index, then performing the update,
> + and then recreating the index will be faster than a routine update,
> + however, one should review the delayed indexing technique used for
> + <acronym>GIN</acronym> (see <xref linkend="gin-fast-update"/> for
> + details) and the options it provides.

We are losing some context with this formulation, particularly for the
case of the insertion of multiple keys. So I think that it is better
to just remove the Postgres 8.4 bit, and keep the second paragraph
mostly as-is.

> - <para>
> - As of <productname>PostgreSQL</productname> 9.1, null key values can be
> - included in the index. Also, placeholder nulls are included in the index
> - for indexed items that are null or contain no keys according to
> - <function>extractValue</function>. This allows searches that should find empty
> - items to do so.
> - </para>

Let's keep that, as agreed upthread.

> <para>
> Multicolumn <acronym>GIN</acronym> indexes are implemented by building
> a single B-tree over composite values (column number, key value). The
> @@ -507,7 +499,7 @@
> Updating a <acronym>GIN</acronym> index tends to be slow because of the
> intrinsic nature of inverted indexes: inserting or updating one heap row
> can cause many inserts into the index (one for each key extracted
> - from the indexed item). As of <productname>PostgreSQL</productname> 8.4,
> + from the indexed item).
> <acronym>GIN</acronym> is capable of postponing much of this work by inserting
> new tuples into a temporary, unsorted list of pending entries.
> When the table is vacuumed or autoanalyzed, or when

Agreed to remove this reference to 8.4.

> - this operation while the server is running. Note that in PostgreSQL 9.1
> - and earlier you will also need to update the <structname>pg_tablespace</structname>
> - catalog with the new locations. (If you do not, <literal>pg_dump</literal> will
> - continue to output the old tablespace locations.)
> + this operation while the server is running.
> </para>

I think that this should be kept. pg_dump is supported with 9.1.

> - <para>
> - Previous releases failed to preserve a lock which is upgraded by a later
> - savepoint. For example, this code:
> -<programlisting>
> -BEGIN;
> -SELECT * FROM mytable WHERE key = 1 FOR UPDATE;
> -SAVEPOINT s;
> -UPDATE mytable SET ... WHERE key = 1;
> -ROLLBACK TO s;
> -</programlisting>
> - would fail to preserve the <literal>FOR UPDATE</literal> lock after the
> - <command>ROLLBACK TO</command>. This has been fixed in release 9.3.
> - </para>

Feels a bit early to remove IMO.

> - <para>
> - Note that if a <literal>FROM</literal> clause is not specified,
> - the query cannot reference any database tables. For example, the
> - following query is invalid:
> -<programlisting>
> -SELECT distributors.* WHERE distributors.name = 'Westward';
> -</programlisting><productname>PostgreSQL</productname> releases prior to
> - 8.1 would accept queries of this form, and add an implicit entry
> - to the query's <literal>FROM</literal> clause for each table
> - referenced by the query. This is no longer allowed.
> - </para>
> </refsect2>

OK to remove the whole paragraph here.

> - <para>
> - The ability to use names to reference SQL function arguments was added
> - in <productname>PostgreSQL</productname> 9.2. Functions to be used in
> - older servers must use the <literal>$<replaceable>n</replaceable></literal> notation.
> - </para>
> - </note>
> </sect2>

I think that's too early to remove.

So this comes down to 5 items, as per the attached. Thoughts?
--
Michael