1 files changed, 45 insertions, 28 deletions

diff --git a/doc/src/sgml/bki.sgml b/doc/src/sgml/bki.sgml
index 5f80f9ed24d..0dd753bc6f5 100644
--- a/doc/src/sgml/bki.sgml
+++ b/doc/src/sgml/bki.sgml
@@ -187,11 +187,10 @@
 # A comment could appear here.
 { oid => '1', oid_symbol => 'TemplateDbOid',
   descr => 'database\'s default template',
-  datname => 'template1', datdba => 'PGUID', encoding => 'ENCODING',
-  datcollate => 'LC_COLLATE', datctype => 'LC_CTYPE', datistemplate => 't',
-  datallowconn => 't', datconnlimit => '-1', datlastsysoid => '0',
-  datfrozenxid => '0', datminmxid => '1', dattablespace => '1663',
-  datacl => '_null_' },
+  datname => 'template1', encoding => 'ENCODING', datcollate => 'LC_COLLATE',
+  datctype => 'LC_CTYPE', datistemplate => 't', datallowconn => 't',
+  datconnlimit => '-1', datlastsysoid => '0', datfrozenxid => '0',
+  datminmxid => '1', dattablespace => 'pg_default', datacl => '_null_' },
 
 ]
 </programlisting>
@@ -229,6 +228,9 @@
       While the metadata keys are optional, the catalog's defined columns
       must all be provided, except when the catalog's <literal>.h</literal>
       file specifies a default value for the column.
+      (In the example above, the <structfield>datdba</structfield> field has
+      been omitted because <filename>pg_database.h</filename> supplies a
+      suitable default value for it.)
      </para>
     </listitem>
 
@@ -264,8 +266,10 @@
 
     <listitem>
      <para>
-      To aid readability, field values that are OIDs of other catalog
-      entries can be represented by names rather than numeric OIDs.
+      Field values that are OIDs of other catalog entries should be
+      represented by symbolic names rather than actual numeric OIDs.
+      (In the example above, <structfield>dattablespace</structfield>
+      contains such a reference.)
       This is described in <xref linkend="system-catalog-oid-references"/>
       below.
      </para>
@@ -438,13 +442,13 @@
    <title>OID Reference Lookup</title>
 
    <para>
-    Cross-references from one initial catalog row to another can be written
-    by just writing the preassigned OID of the referenced row.  But
-    that's error-prone and hard to understand, so for frequently-referenced
-    catalogs, <filename>genbki.pl</filename> provides mechanisms to write
-    symbolic references instead.  Currently this is possible for references
-    to access methods, functions, languages,
-    operators, opclasses, opfamilies, types, and encodings.
+    In principle, cross-references from one initial catalog row to another
+    could be written just by writing the preassigned OID of the referenced
+    row in the referencing field.  However, that is against project
+    policy, because it is error-prone, hard to read, and subject to
+    breakage if a newly-assigned OID is renumbered.  Therefore
+    <filename>genbki.pl</filename> provides mechanisms to write
+    symbolic references instead.
     The rules are as follows:
    </para>
 
@@ -455,19 +459,20 @@
       Use of symbolic references is enabled in a particular catalog column
       by attaching <literal>BKI_LOOKUP(<replaceable>lookuprule</replaceable>)</literal>
       to the column's definition, where <replaceable>lookuprule</replaceable>
-      is <literal>pg_am</literal>, <literal>pg_proc</literal>,
-      <literal>pg_language</literal>,
-      <literal>pg_operator</literal>, <literal>pg_opclass</literal>,
-      <literal>pg_opfamily</literal>,
-      <literal>pg_type</literal>,
-      or <literal>encoding</literal>.
+      is the name of the referenced catalog, e.g. <literal>pg_proc</literal>.
       <literal>BKI_LOOKUP</literal> can be attached to columns of
       type <type>Oid</type>, <type>regproc</type>, <type>oidvector</type>,
       or <type>Oid[]</type>; in the latter two cases it implies performing a
       lookup on each element of the array.
-      It's also permissible to attach <literal>BKI_LOOKUP</literal>
-      to integer columns; this should be done only for encodings,
-      which are not currently represented as catalog OIDs.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      It's also permissible to attach <literal>BKI_LOOKUP(encoding)</literal>
+      to integer columns to reference character set encodings, which are
+      not currently represented as catalog OIDs, but have a set of values
+      known to <filename>genbki.pl</filename>.
      </para>
     </listitem>
 
@@ -483,10 +488,11 @@
 
     <listitem>
      <para>
-      Access methods are just represented by their names, as are types.
-      Type names must match the referenced <structname>pg_type</structname>
-      entry's <structfield>typname</structfield>; you do not get to use any
-      aliases such as <literal>integer</literal>
+      Most kinds of catalog objects are simply referenced by their names.
+      Note that type names must exactly match the
+      referenced <structname>pg_type</structname>
+      entry's <structfield>typname</structfield>; you do not get to use
+      any aliases such as <literal>integer</literal>
       for <literal>int4</literal>.
      </para>
     </listitem>
@@ -530,7 +536,18 @@
      <para>
       In none of these cases is there any provision for
       schema-qualification; all objects created during bootstrap are
-      expected to be in the pg_catalog schema.
+      expected to be in the <literal>pg_catalog</literal> schema.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      In addition to the generic lookup mechanisms, there is a special
+      convention that <literal>PGNSP</literal> is replaced by the OID of
+      the <literal>pg_catalog</literal> schema,
+      and <literal>PGUID</literal> is replaced by the OID of the bootstrap
+      superuser role.  These usages are somewhat historical but so far
+      there hasn't been a need to generalize them.
      </para>
     </listitem>
    </itemizedlist>