Suggest shell here-documents instead of psql -c for multiple commands.

The documentation suggested using "echo | psql", but not the often-superior
alternative of a here-document.  Also, be more direct about suggesting
that people avoid -c for multiple commands.  Per discussion.

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 49ad740a4c3265c027ab0b3784d904c7afe1245b..803fc503a64ef964fef2719345c941f62c543990 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -88,8 +88,8 @@ PostgreSQL documentation
       or a single backslash command. Thus you cannot mix
       <acronym>SQL</acronym> and <application>psql</application>
       meta-commands with this option. To achieve that, you could
-      pipe the string into <application>psql</application>, like
-      this: <literal>echo '\x \\ SELECT * FROM foo;' | psql</literal>.
+      pipe the string into <application>psql</application>, for example:
+      <literal>echo '\x \\ SELECT * FROM foo;' | psql</literal>.
       (<literal>\\</> is the separator meta-command.)
       </para>
       <para>
@@ -98,7 +98,21 @@ PostgreSQL documentation
        <command>BEGIN</>/<command>COMMIT</> commands included in the
        string to divide it into multiple transactions.  This is
        different from the behavior when the same string is fed to
-       <application>psql</application>'s standard input.
+       <application>psql</application>'s standard input.  Also, only
+       the result of the last SQL command is returned.
+      </para>
+      <para>
+       Because of these legacy behaviors, putting more than one command in
+       the <option>-c</option> string often has unexpected results.  It's
+       better to feed multiple commands to <application>psql</application>'s
+       standard input, either using <application>echo</application> as
+       illustrated above, or via a shell here-document, for example:
+<programlisting>
+psql &lt;&lt;EOF
+\x
+SELECT * FROM foo;
+EOF
+</programlisting>
       </para>
       </listitem>
     </varlistentry>