Re: [doc] remove reference to pg_dump pre-8.1 switch behaviour - Mailing list pgsql-hackers

Heikki Linnakangas <hlinnaka@iki.fi> writes:
> On 23/10/2020 17:51, Tom Lane wrote:
>> Seems like we could have gotten rid of that by now, but when exactly
>> does it become fair game?  And can we have a non-ad-hoc process for
>> getting rid of such cruft?

> I did some grepping for strings like "version 7", "pre-8" and so on. I
> couldn't come up with a clear rule on what could be removed. Context
> matters.

Yeah, that's unsurprising.  But thanks for all the effort you put into
this review!

> Findings in detail follow. And attached is a patch about the stuff that
> I think can be removed pretty straightforwardly.

I agree with the patch, and with your other thoughts, except as noted
below.

> config.sgml (on synchronized_scans):

>          have no <literal>ORDER BY</literal> clause.  Setting this parameter to
>          <literal>off</literal> ensures the pre-8.3 behavior in which a sequential
>          scan always starts from the beginning of the table.  The default
>          is <literal>on</literal>.

> We could remove the reference to 8.3 version. I'm inclined to keep it
> though.

Maybe s/pre-8.3/simple/, or some similar adjective?

> func.sgml:
>     <note>
>       <para>
>       Before <productname>PostgreSQL</productname> 8.2, the containment
>       operators <literal>@></literal> and <literal><@</literal>
> were respectively
>       called <literal>~</literal> and <literal>@</literal>.  These names
> are still
>       available, but are deprecated and will eventually be removed.
>      </para>
>     </note>

> The old names are still available, so should keep this.

Perhaps it's time to actually remove those operators as threatened here?
That's material for a separate discussion, though.

>     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.)
>    </para>

> Could remove it.

Yeah, I'm OK with removing the parenthetical comment.

>       There are two differences in the behavior of <function>string_to_array</function>
>       from pre-9.1 versions of <productname>PostgreSQL</productname>.

> Feels too early to remove.

+1.  9.1 was in support till ~4 years ago; 8.2 EOL'd 9 years ago.
I'm not sure where to put the cutoff, but 4 years seems too little.

>    <note>
>     <para>
>      Prior to <productname>PostgreSQL</productname> 8.2, the
>      <literal><</literal>, <literal><=</literal>,
> <literal>></literal> and <literal>>=</literal>
>      cases were not handled per SQL specification.  A comparison like
>      <literal>ROW(a,b) < ROW(c,d)</literal>
>      was implemented as
>      <literal>a < c AND b < d</literal>
>      whereas the correct behavior is equivalent to
>      <literal>a < c OR (a = c AND b < d)</literal>.
>     </para>
>    </note>

> Important incompatibility. Although very old. I'm inclined to keep it.
> If we remove it, it'd still be useful to explain the new behavior.

Yeah, even if we don't care about 8.2, some of this text is useful
to clarify the behavior of row comparisons.  I haven't looked at
the surrounding material, but I'd not want to just delete this
unless it's clearly duplicative.

>       As of <productname>PostgreSQL</productname> 8.4, this advice is less
>       necessary since delayed indexing is used (see <xref
>       linkend="gin-fast-update"/> for details).  But for very large updates
>       it may still be best to drop and recreate the index.

> I think that's old enough, but the paragraph would need some
> copy-editing, not just removal.

Right, same deal, needs a bit of wordsmithing not just deletion.

>       <replaceable class="parameter">mode</replaceable> is unused and
>       ignored as of <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>.

> We need to say something about 'mode'. Keep.

Maybe s/as of/since/, but otherwise fine.

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

> Could replace the "as of PostgreSQL 7.4" with "Currently", but it's not
> much shorter.

While it's not shorter, I think it's clearer in this context.  7.4
is far enough back that a reader might expect the next sentence to
offer updated info.

>     <!-- TODO we need to put a date on these numbers? -->
>    <para>
>     Another example — the <productname>PostgreSQL</productname>
> mailing
>     list archives contained 910,989 unique words with 57,491,343 lexemes in
>     461,020 messages.
>    </para>

> Refresh the numbers.

I agree with the comment: if we keep this, there should be an "as of" date
associated with the numbers.

Thanks again for slogging through that!

            regards, tom lane