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 7ed20e4dd9adba314ec515ee12029486c498de6b..94635c56ce9c089d2bda533b65f2260e043b43ce 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -83,14 +83,15 @@ PostgreSQL documentation
       (psqlrc and ~/.psqlrc) are
       ignored with this option.
       
-      command must be either
+      
+      command must be either
       a command string that is completely parsable by the server (i.e.,
       it contains no psql-specific features),
       or a single backslash command. Thus you cannot mix
       SQL and psql
       meta-commands with this option. To achieve that, you could
-      pipe the string into psql, like
-      this: echo '\x \\ SELECT * FROM foo;' | psql.
+      pipe the string into psql, for example:
+      echo '\x \\ SELECT * FROM foo;' | psql.
       (\\ is the separator meta-command.)
       
       
@@ -102,6 +103,19 @@ PostgreSQL documentation
        psql's standard input.  Also, only
        the result of the last SQL command is returned.
       
+      
+       Because of these legacy behaviors, putting more than one command in
+       the -c string often has unexpected results.  It's
+       better to feed multiple commands to psql's
+       standard input, either using echo as
+       illustrated above, or via a shell here-document, for example:
+
+psql <<EOF
+\x
+SELECT * FROM foo;
+EOF
+
+