<para>
      Comments are preceded by <literal>#</literal>, and must be on their
      own lines.
     </para>
    </listitem>

    <listitem>
     <para>
      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>
    </listitem>

    <listitem>
     <para>
      Since hashes are unordered data structures, field order and line
      layout aren't semantically significant.  However, to maintain a
      consistent appearance, we set a few rules that are applied by the
      formatting script <filename>reformat_dat_file.pl</filename>:

      <itemizedlist>

       <listitem>
        <para>
         Within each pair of curly braces, the metadata
         fields <literal>oid</literal>, <literal>oid_symbol</literal>,
         <literal>array_type_oid</literal>, and <literal>descr</literal>
         (if present) come first, in that order, then the catalog's own
         fields appear in their defined order.
        </para>
       </listitem>

       <listitem>
        <para>
         Newlines are inserted between fields as needed to limit line length
         to 80 characters, if possible.  A newline is also inserted between
         the metadata fields and the regular fields.
        </para>
       </listitem>

       <listitem>
        <para>
         If the catalog's <literal>.h</literal> file specifies a default
         value for a column, and a data entry has that same
         value, <filename>reformat_dat_file.pl</filename> will omit it from
         the data file.  This keeps the data representation compact.
        </para>
       </listitem>

       <listitem>
        <para>
         <filename>reformat_dat_file.pl</filename> preserves blank lines
         and comment lines as-is.
        </para>
       </listitem>

      </itemizedlist>

      It's recommended to run <filename>reformat_dat_file.pl</filename>
      before submitting catalog data patches.  For convenience, you can
      simply change to <filename>src/include/catalog/</filename> and
      run <literal>make reformat-dat-files</literal>.
     </para>
    </listitem>

    <listitem>
     <para>
      If you want to add a new method of making the data representation
      smaller, you must implement it
      in <filename>reformat_dat_file.pl</filename> and also
      teach <function>Catalog::ParseData()</function> how to expand the
      data back into the full representation.
     </para>
    </listitem>

   </itemizedlist>
  </sect2>

  <sect2 id="system-catalog-oid-assignment">
   <title>OID Assignment</title>

   <para>
    A catalog row appearing in the initial data can be given a
    manually-assigned OID by writing an <literal>oid
    =&gt; <replaceable>nnnn</replaceable></literal> metadata field.
    Furthermore, if an OID is assigned, a C macro for that OID can be
    created by writing an <literal>oid_symbol
    =&gt; <replaceable>name</replaceable></literal> metadata field.
   </para>

   <para>
    Pre-loaded catalog rows must have preassigned OIDs if there are OID
    references to them in other pre-loaded rows.  A preassigned OID is
    also needed if the row's OID must be referenced from C code.
    If neither case applies, the <literal>oid</literal> metadata field can
    be omitted, in which case the bootstrap code assigns an OID
    automatically.
    In practice we usually preassign OIDs for all or none of the pre-loaded
    rows in a given catalog, even if only some of them are actually
    cross-referenced.
   </para>

   <para>
    Writing the actual numeric value of any OID in C code is considered
    very bad form; always use a macro, instead.  Direct references
    to <structname>pg_proc</structname> OIDs are common enough that there's
    a special mechanism to