Re: Removal of backward-compatibility docs mentions - Mailing list pgsql-patches

[ Sorry for the two copies, Bruce: I forgot to CC the list previously ]

On Mon, 2006-03-20 at 13:57 -0500, Bruce Momjian wrote:
> The attached patch removes or minimizes some documentation mentions of
> backward compatibility for release 7.2 and earlier.

I don't think it's a net win to get rid of this text, as it describes
useful alternatives to the GUC variable:

*** doc/src/sgml/config.sgml    10 Mar 2006 19:10:47 -0000      1.52
--- doc/src/sgml/config.sgml    20 Mar 2006 18:40:44 -0000
***************
*** 3789,3801 ****
        <listitem>
         <para>
          This controls the inheritance semantics, in particular whether
!         subtables are included by various commands by default. They
were
!         not included in versions prior to 7.1. If you need the old
!         behavior you can set this variable to <literal>off</>, but in
!         the long run you are encouraged to change your applications to
!         use the <literal>ONLY</literal> key word to exclude subtables.
!         See <xref linkend="ddl-inherit"> for more information about
!         inheritance.
         </para>
        </listitem>
       </varlistentry>
--- 3789,3796 ----
        <listitem>
         <para>
          This controls the inheritance semantics, in particular whether
!         subtables are included by various commands by default. This
was
!         added for compatibility with releases prior to 7.1.
         </para>
        </listitem>
       </varlistentry>

*** doc/src/sgml/libpq.sgml     10 Mar 2006 19:10:48 -0000      1.206
--- doc/src/sgml/libpq.sgml     20 Mar 2006 18:41:05 -0000
***************
*** 689,699 ****
  functions described below to get
  at the contents of <structname>PGconn</structname>.  Avoid directly
referencing the fields of the
  <structname>PGconn</> structure because they are subject to change in
the future.
- (Beginning in <productname>PostgreSQL</productname> release 6.4, the
- definition of the <type>struct</type> behind <structname>PGconn</> is
not even provided in <filename>libpq-fe.h</filename>.
- If you have old code that accesses <structname>PGconn</structname>
fields directly, you can keep using it
- by including <filename>libpq-int.h</filename> too, but you are
encouraged to fix the code
- soon.)
  </para>
  </tip>

Removing the information about libpq-int.h but keeping the suggestion to
"avoid directly referencing fields of the PGconn structure" doesn't seem
consistent: the user *can't* directly reference fields without including
libpq-int.h. So I think this hunk should be kept.

The second hunk modified in maintenance.sgml removes some useful
information (ANALYZE collects rows by random sampling).

From storage.sgml:

!  Since <productname>PostgreSQL</productname> uses a fixed page size
(commonly
! 8Kb), and does not allow tuples to span multiple pages, so it's not
possible to
! store very large field values directly.

That is poorly phrased ("Since ..., so it's not").

-Neil