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 id="error-style-guide-quotes">
   <title>Use of Quotes</title>

   <para>
    Always use quotes to delimit file names, user-supplied identifiers,
    configuration variable names, and other variables that might contain
    words.  Do not use them to mark up variables that will not contain words
    (for example, operator names).
   </para>

   <para>
    There are functions in the backend that will double-quote their own output
    as needed (for example, <function>format_type_be()</function>).  Do not put
    additional quotes around the output of such functions.
   </para>

   <para>
    Rationale: Objects can have names that create ambiguity when embedded in a
    message.  Be consistent about denoting where a plugged-in name starts and
    ends.  But don't clutter messages with unnecessary or duplicate quote
    marks.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-grammar-punctuation">
   <title>Grammar and Punctuation</title>

   <para>
    The rules are different for primary error messages and for detail/hint
    messages:
   </para>

   <para>
    Primary error messages: Do not capitalize the first letter.  Do not end a
    message with a period.  Do not even think about ending a message with an
    exclamation point.
   </para>

   <para>
    Detail and hint messages: Use complete sentences, and end each with
    a period.  Capitalize the first word of sentences.  Put two spaces after
    the period if another sentence follows (for English text; might be
    inappropriate in other languages).
   </para>

   <para>
    Error context strings: Do not capitalize the first letter and do
    not end the string with a period.  Context strings should normally
    not be complete sentences.
   </para>

   <para>
    Rationale: Avoiding punctuation makes it easier for client applications to
    embed the message into a variety of grammatical contexts.  Often, primary
    messages are not grammatically complete sentences anyway.  (And if they're
    long enough to be more than one sentence, they should be split into
    primary and detail parts.)  However, detail and hint messages are longer
    and might need to include multiple sentences.  For consistency, they should
    follow complete-sentence style even when there's only one sentence.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-case">
   <title>Upper Case vs. Lower Case</title>

   <para>
    Use lower case for message wording, including the first letter of a
    primary error message.  Use upper case for SQL commands and key words if
    they appear in the message.
   </para>

   <para>
    Rationale: It's easier to make everything look more consistent this
    way, since some messages are complete sentences and some not.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-passive-voice">
   <title>Avoid Passive Voice</title>

   <para>
    Use the active voice.  Use complete sentences when there is an acting
    subject (<quote>A could not