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 do B</quote>).  Use telegram style without
    subject if the subject would be the program itself; do not use
    <quote>I</quote> for the program.
   </para>

   <para>
    Rationale: The program is not human.  Don't pretend otherwise.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-tense">
   <title>Present vs. Past Tense</title>

   <para>
    Use past tense if an attempt to do something failed, but could perhaps
    succeed next time (perhaps after fixing some problem).  Use present tense
    if the failure is certainly permanent.
   </para>

   <para>
    There is a nontrivial semantic difference between sentences of the form:
<programlisting>
could not open file "%s": %m
</programlisting>
and:
<programlisting>
cannot open file "%s"
</programlisting>
    The first one means that the attempt to open the file failed.  The
    message should give a reason, such as <quote>disk full</quote> or
    <quote>file doesn't exist</quote>.  The past tense is appropriate because
    next time the disk might not be full anymore or the file in question might
    exist.
   </para>

   <para>
    The second form indicates that the functionality of opening the named file
    does not exist at all in the program, or that it's conceptually
    impossible.  The present tense is appropriate because the condition will
    persist indefinitely.
   </para>

   <para>
    Rationale: Granted, the average user will not be able to draw great
    conclusions merely from the tense of the message, but since the language
    provides us with a grammar we should use it correctly.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-object-type">
   <title>Type of the Object</title>

   <para>
    When citing the name of an object, state what kind of object it is.
   </para>

   <para>
    Rationale: Otherwise no one will know what <quote>foo.bar.baz</quote>
    refers to.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-brackets">
   <title>Brackets</title>

   <para>
    Square brackets are only to be used (1) in command synopses to denote
    optional arguments, or (2) to denote an array subscript.
   </para>

   <para>
    Rationale: Anything else does not correspond to widely-known customary
    usage and will confuse people.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-error-messages">
   <title>Assembling Error Messages</title>

   <para>
   When a message includes text that is generated elsewhere, embed it in
   this style:
<programlisting>
could not open file %s: %m
</programlisting>
   </para>

   <para>
    Rationale: It would be difficult to account for all possible error codes
    to paste this into a single smooth sentence, so some sort of punctuation
    is needed.  Putting the embedded text in parentheses has also been
    suggested, but it's unnatural if the embedded text is likely to be the
    most important part of the message, as is often the case.
   </para>

  </simplesect>

  <simplesect