Sync commentary in transam.h and bki.sgml.

Commit a6417078c missed updating some comments in transam.h about
reservation of high OIDs for development purposes.  Also tamp down
an over-optimistic comment there about how easy it'd be to change
FirstNormalObjectId.

Earlier, commit 09568ec3d failed to update bki.sgml for the split
between genbki.pl-assigned OIDs and those assigned during initdb.

Also fix genbki.pl so that it will complain if it overruns
that split.  It's possible that doing so would have no very bad
consequences, but that's no excuse for not detecting it.

doc/src/sgml/bki.sgml

@@ -422,19 +422,21 @@
    </para>
 
    <para>
-    The OID counter starts at 10000 at the beginning of a bootstrap run.
+    If <filename>genbki.pl</filename> needs to assign an OID to a catalog
-    If a row from a source other than <filename>postgres.bki</filename>
+    entry that does not have a manually-assigned OID, it will use a value in
-    is inserted into a table that requires OIDs, then it will receive an
+    the range 10000&mdash;11999.  The server's OID counter is set to 12000
-    OID of 10000 or above.  For example, objects created while running
+    at the start of a bootstrap run.  Thus objects created by regular SQL
-    the <filename>information_schema.sql</filename> script receive such
+    commands during the later phases of bootstrap, such as objects created
-    OIDs.
+    while running the <filename>information_schema.sql</filename> script,
+    receive OIDs of 12000 or above.
    </para>
 
    <para>
     OIDs assigned during normal database operation are constrained to be
-    16384 or higher.  This leaves the range 10000&mdash;16383 available
+    16384 or higher.  This ensures that the range 10000&mdash;16383 is free
-    for OIDs assigned automatically during bootstrap.  These OIDs are not
+    for OIDs assigned automatically by <filename>genbki.pl</filename> or
-    considered stable, and may change from one installation to another.
+    during bootstrap.  These automatically-assigned OIDs are not considered
+    stable, and may change from one installation to another.
    </para>
   </sect2>
 

src/backend/catalog/genbki.pl

@@ -138,10 +138,13 @@ die "found $found duplicate OID(s) in catalog data\n" if $found;
 
 
 # Oids not specified in the input files are automatically assigned,
-# starting at FirstGenbkiObjectId.
+# starting at FirstGenbkiObjectId, extending up to FirstBootstrapObjectId.
 my $FirstGenbkiObjectId =
   Catalog::FindDefinedSymbol('access/transam.h', $include_path,
 	'FirstGenbkiObjectId');
+my $FirstBootstrapObjectId =
+  Catalog::FindDefinedSymbol('access/transam.h', $include_path,
+	'FirstBootstrapObjectId');
 my $GenbkiNextOid = $FirstGenbkiObjectId;
 
 
@@ -625,6 +628,11 @@ foreach my $declaration (@index_decls)
 # last command in the BKI file: build the indexes declared above
 print $bki "build indices\n";
 
+# check that we didn't overrun available OIDs
+die
+  "genbki OID counter reached $GenbkiNextOid, overrunning FirstBootstrapObjectId\n"
+  if $GenbkiNextOid > $FirstBootstrapObjectId;
+
 
 # Now generate schemapg.h
 

src/include/access/transam.h

@@ -72,10 +72,13 @@
  *		Object ID (OID) zero is InvalidOid.
  *
  *		OIDs 1-9999 are reserved for manual assignment (see .dat files in
- *		src/include/catalog/), with 9000-9999 tentatively reserved for forks.
+ *		src/include/catalog/).  Of these, 8000-9999 are reserved for
+ *		development purposes (such as in-progress patches and forks);
+ *		they should not appear in released versions.
  *
- *		OIDs 10000-11999 are reserved for assignment by genbki.pl, when the
+ *		OIDs 10000-11999 are reserved for assignment by genbki.pl, for use
- *		.dat files in src/include/catalog/ do not specify oids.
+ *		when the .dat files in src/include/catalog/ do not specify an OID
+ *		for a catalog entry that requires one.
  *
  *		OIDS 12000-16383 are reserved for assignment during initdb
  *		using the OID generator.  (We start the generator at 12000.)
@@ -84,9 +87,13 @@
  *		during normal multiuser operation.  (We force the generator up to
  *		16384 as soon as we are in normal operation.)
  *
- * The choices of 10000, 12000 and 16384 are completely arbitrary, and can be
+ * The choices of 8000, 10000 and 12000 are completely arbitrary, and can be
- * moved if we run low on OIDs in either category.  Changing the macros below
+ * moved if we run low on OIDs in any category.  Changing the macros below,
- * should be sufficient to do this.
+ * and updating relevant documentation (see bki.sgml and RELEASE_CHANGES),
+ * should be sufficient to do this.  Moving the 16384 boundary between
+ * initdb-assigned OIDs and user-defined objects would be substantially
+ * more painful, however, since some user-defined OIDs will appear in
+ * on-disk data; such a change would probably break pg_upgrade.
  *
  * NOTE: if the OID generator wraps around, we skip over OIDs 0-16383
  * and resume with 16384.  This minimizes the odds of OID conflict, by not