<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 id="error-style-guide-error-reasons">
   <title>Reasons for Errors</title>

   <para>
    Messages should always state the reason why an error occurred.
    For example:
<programlisting>
BAD:    could not open file %s
BETTER: could not open file %s (I/O failure)
</programlisting>
    If no reason is known you better fix the code.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-function-names">
   <title>Function Names</title>

   <para>
    Don't include the name of the reporting routine in the error text. We have
    other mechanisms for finding that out when needed, and for most users it's
    not helpful information.  If the error text doesn't make as much sense
    without the function name, reword it.
<programlisting>
BAD:    pg_strtoint32: error in "z": cannot parse "z"
BETTER: invalid input syntax for type integer: "z"
</programlisting>
   </para>

   <para>
    Avoid mentioning called function names, either; instead say what the code
    was trying to do:
<programlisting>
BAD:    open() failed: %m
BETTER: could not open file %s: %m
</programlisting>
    If it really seems necessary, mention the system call in the detail
    message.  (In some cases, providing the actual values passed to the
    system call might be appropriate information for the detail message.)
   </para>

   <para>
    Rationale: Users don't know what all those functions do.
   </para>

  </simplesect>

  <simplesect id="error-style-guide-tricky-words">
   <title>Tricky Words to Avoid</title>

  <formalpara>
    <title>Unable</title>
   <para>
    <quote>Unable</quote> is nearly the passive voice.  Better use
    <quote>cannot</quote> or <quote>could not</quote>, as appropriate.
   </para>
  </formalpara>

  <formalpara>
    <title>Bad</title>
   <para>
    Error messages like <quote>bad result</quote> are really hard to interpret
    intelligently.  It's better to write why the result is <quote>bad</quote>,
    e.g., <quote>invalid format</quote>.
   </para>
  </formalpara>

  <formalpara>
    <title>Illegal</title>
   <para>
    <quote>Illegal</quote> stands for a violation of the law, the rest is
    <quote>invalid</quote>. Better yet, say why it's invalid.
   </para>
  </formalpara>

  <formalpara>
    <title>Unknown</title>
   <para>
    Try to avoid <quote>unknown</quote>.  Consider <quote>error: unknown
    response</quote>.  If you don't know what the response is, how do you know
    it's erroneous? <quote>Unrecognized</quote> is often a better choice.
    Also, be sure to include the value being complained of.
<programlisting>
BAD:    unknown node type
BETTER: unrecognized node type: 42
</programlisting>
   </para>
  </formalpara>

  <formalpara>
    <title>Find vs. Exists</title>
   <para>
    If the program uses a nontrivial algorithm to locate a resource (e.g., a
    path search) and that algorithm fails, it is fair to say that the program
    couldn't <quote>find</quote> the resource.  If, on the other hand, the
    expected