there are enough internal <quote>cannot happen</quote> error checks in the
    system that <function>elog</function> is still widely used; it is preferred for
    those messages for its notational simplicity.
   </para>

   <para>
    Advice about writing good error messages can be found in
    <xref linkend="error-style-guide"/>.
   </para>
  </sect1>

  <sect1 id="error-style-guide">
   <title>Error Message Style Guide</title>

   <para>
    This style guide is offered in the hope of maintaining a consistent,
    user-friendly style throughout all the messages generated by
    <productname>PostgreSQL</productname>.
   </para>

  <simplesect id="error-style-guide-what-goes-where">
   <title>What Goes Where</title>

   <para>
    The primary message should be short, factual, and avoid reference to
    implementation details such as specific function names.
    <quote>Short</quote> means <quote>should fit on one line under normal
    conditions</quote>.  Use a detail message if needed to keep the primary
    message short, or if you feel a need to mention implementation details
    such as the particular system call that failed. Both primary and detail
    messages should be factual.  Use a hint message for suggestions about what
    to do to fix the problem, especially if the suggestion might not always be
    applicable.
   </para>

   <para>
    For example, instead of:
<programlisting>
IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
(plus a long addendum that is basically a hint)
</programlisting>
    write:
<programlisting>
Primary:    could not create shared memory segment: %m
Detail:     Failed syscall was shmget(key=%d, size=%u, 0%o).
Hint:       The addendum, written as a complete sentence.
</programlisting>
   </para>

   <para>
    Rationale: keeping the primary message short helps keep it to the point,
    and lets clients lay out screen space on the assumption that one line is
    enough for error messages.  Detail and hint messages can be relegated to a
    verbose mode, or perhaps a pop-up error-details window.  Also, details and
    hints would normally be suppressed from the server log to save
    space. Reference to implementation details is best avoided since users
    aren't expected to know the details.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-formatting">
   <title>Formatting</title>

   <para>
    Don't put any specific assumptions about formatting into the message
    texts.  Expect clients and the server log to wrap lines to fit their own
    needs.  In long messages, newline characters (\n) can be used to indicate
    suggested paragraph breaks.  Don't end a message with a newline.  Don't
    use tabs or other formatting characters.  (In error context displays,
    newlines are automatically added to separate levels of context such as
    function calls.)
   </para>

   <para>
    Rationale: Messages are not necessarily displayed on terminal-type
    displays.  In GUI displays or browsers these formatting instructions are
    at best ignored.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-quotation-marks">
   <title>Quotation Marks</title>

   <para>
    English text should use double quotes when quoting is appropriate.
    Text in other languages should consistently use one kind of quotes that is
    consistent with publishing customs and computer output of other programs.
   </para>

   <para>
    Rationale: The choice of double quotes over single quotes is somewhat
    arbitrary, but tends to be the preferred use.  Some have suggested
    choosing the kind of quotes depending on the type of object according to
    SQL conventions (namely, strings single quoted, identifiers double
    quoted).  But this is a language-internal technical issue that many users
    aren't even familiar with, it won't scale to other kinds of quoted terms,
    it doesn't translate to other languages, and it's pretty pointless, too.
   </para>

  </simplesect>

  <simplesect