Doc: update ddl.sgml's description of cmin and cmax.

We long ago folded these two tuple header fields into one field
to save space.  However, nothing was done to the user-facing
documentation about them, perhaps with the idea that we'd add
code to emit something approximating the original definitions.
That never happened and presumably never will, so update the
text to reflect current reality.

Author: Paul A Jungwirth <pj@illuminatedcomputing.com>
Co-authored-by: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/CA+renyVYYboiTayRRE0j1oKpeB+NjEBSUXfwgEu6O0JESSmauQ@mail.gmail.com

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index bd8cb461cba4f8005c36e25fa9af8a66be50f626..747f929aee323a112babce8a3c7118207ad2eb36 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1501,33 +1501,42 @@ CREATE TABLE circles (
     </listitem>
    </varlistentry>
 
     </listitem>
    </varlistentry>
 

-   <varlistentry id="ddl-system-columns-cmin">
-    <term><structfield>cmin</structfield></term>
+   <varlistentry id="ddl-system-columns-xmax">
+    <term><structfield>xmax</structfield></term>

     <listitem>
      <indexterm>
     <listitem>
      <indexterm>

-      <primary>cmin</primary>
+      <primary>xmax</primary>

      </indexterm>
 
      <para>
      </indexterm>
 
      <para>

-      The command identifier (starting at zero) within the inserting
-      transaction.
+      The identity (transaction ID) of the deleting transaction, or
+      zero for an undeleted row version.  It is possible for this column to
+      be nonzero in a visible row version. That usually indicates that the
+      deleting transaction hasn't committed yet, or that an attempted
+      deletion was rolled back.

      </para>
     </listitem>
    </varlistentry>
 
      </para>
     </listitem>
    </varlistentry>
 

-   <varlistentry id="ddl-system-columns-xmax">
-    <term><structfield>xmax</structfield></term>
+   <varlistentry id="ddl-system-columns-cmin">
+    <term><structfield>cmin</structfield></term>

     <listitem>
      <indexterm>
     <listitem>
      <indexterm>

-      <primary>xmax</primary>
+      <primary>cmin</primary>

      </indexterm>
 
      <para>
      </indexterm>
 
      <para>

-      The identity (transaction ID) of the deleting transaction, or
-      zero for an undeleted row version.  It is possible for this column to
-      be nonzero in a visible row version. That usually indicates that the
-      deleting transaction hasn't committed yet, or that an attempted
-      deletion was rolled back.
+      Originally, <structfield>cmin</structfield>
+      and <structfield>cmax</structfield> were separate fields.
+      <structfield>cmin</structfield> was the inserting command's command
+      identifier (starting at zero) within the inserting transaction,
+      while <structfield>cmax</structfield> was the deleting command's
+      command identifier within the deleting transaction, or zero if no
+      delete attempt had occurred yet.  Nowadays these columns refer to
+      the same field and will always read as the same value.  That might
+      be the inserting command's command identifier, or the deleting
+      command's command identifier, or a <quote>combocid</quote> that
+      reflects both actions when those happened in the same transaction.

      </para>
     </listitem>
    </varlistentry>
      </para>
     </listitem>
    </varlistentry>


@@ -1540,7 +1549,7 @@ CREATE TABLE circles (
      </indexterm>
 
      <para>
      </indexterm>
 
      <para>

-      The command identifier within the deleting transaction, or zero.
+      See <structfield>cmin</structfield>.

      </para>
     </listitem>
    </varlistentry>
      </para>
     </listitem>
    </varlistentry>