variable-width column.
   Where this rule is inadequate, you can force correct marking by using
   <literal>BKI_FORCE_NOT_NULL</literal>
   and <literal>BKI_FORCE_NULL</literal> annotations as needed.
  </para>

  <para>
   Frontend code should not include any <filename>pg_xxx.h</filename>
   catalog header file, as these files may contain C code that won't compile
   outside the backend.  (Typically, that happens because these files also
   contain declarations for functions
   in <filename>src/backend/catalog/</filename> files.)
   Instead, frontend code may include the corresponding
   generated <filename>pg_xxx_d.h</filename> header, which will contain
   OID <literal>#define</literal>s and any other data that might be of use
   on the client side.  If you want macros or other code in a catalog header
   to be visible to frontend code, write <literal>#ifdef
   EXPOSE_TO_CLIENT_CODE</literal> ... <literal>#endif</literal> around that
   section to instruct <filename>genbki.pl</filename> to copy that section
   to the <filename>pg_xxx_d.h</filename> header.
  </para>

  <para>
   A few of the catalogs are so fundamental that they can't even be created
   by the <acronym>BKI</acronym> <literal>create</literal> command that's
   used for most catalogs, because that command needs to write information
   into these catalogs to describe the new catalog.  These are
   called <firstterm>bootstrap</firstterm> catalogs, and defining one takes
   a lot of extra work: you have to manually prepare appropriate entries for
   them in the pre-loaded contents of <structname>pg_class</structname>
   and <structname>pg_type</structname>, and those entries will need to be
   updated for subsequent changes to the catalog's structure.
   (Bootstrap catalogs also need pre-loaded entries
   in <structname>pg_attribute</structname>, but
   fortunately <filename>genbki.pl</filename> handles that chore nowadays.)
   Avoid making new catalogs be bootstrap catalogs if at all possible.
  </para>
 </sect1>

 <sect1 id="system-catalog-initial-data">
  <title>System Catalog Initial Data</title>

  <para>
   Each catalog that has any manually-created initial data (some do not)
   has a corresponding <literal>.dat</literal> file that contains its
   initial data in an editable format.
  </para>

  <sect2 id="system-catalog-initial-data-format">
   <title>Data File Format</title>

   <para>
    Each <literal>.dat</literal> file contains Perl data structure literals
    that are simply eval'd to produce an in-memory data structure consisting
    of an array of hash references, one per catalog row.
    A slightly modified excerpt from <filename>pg_database.dat</filename>
    will demonstrate the key features:
   </para>

<!-- The "slight modification" is the apostrophe in the description. -->
<programlisting><![CDATA[
[

# A comment could appear here.
{ oid => '1', oid_symbol => 'Template1DbOid',
  descr => 'database\'s default template',
  datname => 'template1', encoding => 'ENCODING',
  datlocprovider => 'LOCALE_PROVIDER', datistemplate => 't',
  datallowconn => 't', dathasloginevt => 'f', datconnlimit => '-1', datfrozenxid => '0',
  datminmxid => '1', dattablespace => 'pg_default', datcollate => 'LC_COLLATE',
  datctype => 'LC_CTYPE', datlocale => 'DATLOCALE', datacl => '_null_' },

]
]]></programlisting>

   <para>
    Points to note:
   </para>

   <itemizedlist>

    <listitem>
     <para>
      The overall file layout is: open square bracket, one or more sets of
      curly braces each of which represents a catalog row, close square
      bracket.  Write a comma after each closing curly brace.
     </para>
    </listitem>

    <listitem>
     <para>
      Within each catalog row, write comma-separated
      <replaceable>key</replaceable> <literal>=&gt;</literal>
      <replaceable>value</replaceable> pairs.  The
      allowed <replaceable>key</replaceable>s are the names of the catalog's
      columns, plus the metadata keys <literal>oid</literal>,