Subject: psql man page error?

From: "Simon Riggs" <[email-masked]>
Date: Tue, 05 Dec 2006 11:57:06 +0000

On the psql man page there is an example of how to perform multiple line
psql script as part of the -c option description.

The example given is

	echo "\x \\ select * from foo;" | psql

which gives

	prompt> echo "\x \\ select * from foo;" | psql
	Expanded display is on.
	invalid command \

i.e. doesn't work on bash. With bash the command should be:

	echo -e "\x \n select * from foo;" | psql

which gives

	prompt> echo -e "\x \n select * from foo;" | psql
	Expanded display is on.
	ERROR:  relation "foo" does not exist

Does this mean there are multiple forms of the echo command, or is this
example just wrong?

-- 
  Simon Riggs             
  EnterpriseDB   http://www.enterprisedb.com

---

From: Jeff Frost <[email-masked]>
Date: Tue, 5 Dec 2006 09:22:36 -0800 (PST)

> Does this mean there are multiple forms of the echo command, or is this

I believe that /bin/echo and the bash built-in used to be slightly different, 
although reviewing both man pages on my FC5 system seem to indicate that they 
have the same command-line arguments.

It's also possible that I'm thinking back to my Solaris (2.5.1) days when the 
built-in tcsh echo was in fact different than /bin/echo.  That's why all my 
scripts seem to call the binary and not the built-in.

Another possibility is that the original author had the options set in his 
xpg_echo environment variable and forgot about it...or his distro was setting 
it in a profile.d file.

-- 
Jeff Frost, Owner 	<[email-masked]>
Frost Consulting, LLC 	http://www.frostconsultingllc.com/
Phone: 650-780-7908	FAX: 650-649-1954

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 5 Dec 2006 12:41:00 -0500 (EST)

> Does this mean there are multiple forms of the echo command, or is this

Intersting.  This example has been around since at least 2002. The SGML
looks like this:

      <application>psql</application>, like this: <literal>echo "\x \\
      select * from foo;" | psql</literal>.

and I suppose the asumption was that the \\ would be at the end of the
output line, but in fact both HTML and manual pages just put the \\
anywhere on the line.  I think the proper fix is:

      <application>psql</application>, like this: <literal>echo -e
      "\\x\nSELECT * FROM foo;" | psql</literal>.

I think all modern operating systems understand echo -e at this point.
Change applied to HEAD and 8.2.X.

-- 
  Bruce Momjian   [email-masked]
  EnterpriseDB    http://www.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +

---

From: Tom Lane <[email-masked]>
Date: Tue, 05 Dec 2006 13:14:45 -0500

Bruce Momjian <[email-masked]> writes:
> I think the proper fix is:

> I think all modern operating systems understand echo -e at this point.

No, they don't, and neither does the Single Unix Spec:
http://www.opengroup.org/onlinepubs/007908799/xcu/echo.html

So your version of the example depends on non-standards-compliant
echo behavior, which is not better than before.

			regards, tom lane

---

From: "Simon Riggs" <[email-masked]>
Date: Tue, 05 Dec 2006 19:57:55 +0000

> echo behavior, which is not better than before.

So the -e is wrong, but the rest of the change was right. Guess we just
need to add a comment about "(you may need to use the -e option on echo
to get this to work on your OS)."

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 5 Dec 2006 18:16:52 -0500 (EST)

> echo behavior, which is not better than before.

Well, at least my example works on _some_ operating systems, while the
previous worked on none of them, so it is _better_.

I can't think of a good way to do this except converting the example to
a <programlisting> block that will not change newlines:

	echo '\x
	SELECT * FROM foo;' | psql

Is that what people want?

---

From: "Simon Riggs" <[email-masked]>
Date: Tue, 05 Dec 2006 23:25:42 +0000

> Is that what people want?

Well, it works, but IMHO its not as clear.

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 5 Dec 2006 23:29:41 -0500 (EST)

> Well, it works, but IMHO its not as clear.

Well, it is even worse because some versions of echo automatically
interpret backslashes, so it would have to be \\x.  I am thinking we
should just leave it as I have it now, unless we want to use 'awk' or
'perl' where we know the backslash behavior.

---

From: Tom Lane <[email-masked]>
Date: Wed, 06 Dec 2006 00:25:26 -0500

> 'perl' where we know the backslash behavior.

The example as you have it now is directly contradictory to the
published spec.

I agree with Simon's suggestion to remove "-e" from the example
(thereby making it spec-compliant) and add a parenthetical remark
suggesting that standards-challenged versions of echo might need "-e".

			regards, tom lane

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 6 Dec 2006 12:03:57 +0100

Am Dienstag, 5. Dezember 2006 18:41 schrieb Bruce Momjian:
> anywhere on the line.

Which is correct.  Removing the \\ alters the point of the example.

-- 
Peter Eisentraut
http://developer.postgresql.org/~petere/

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 6 Dec 2006 09:10:56 -0500 (EST)

> Which is correct.  Removing the \\ alters the point of the example.

Well, if it doesn't render \\ at the end of the line, the example isn't
very clear unless you are looking at the SGML.

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 6 Dec 2006 09:14:01 -0500 (EST)

> suggesting that standards-challenged versions of echo might need "-e".

Well, I just tried Linux and FreeBSD bash (the default shell?) and they
both need '-e' to render '\n' as a newline, so I think we should just
leave it with '-e'.  Following the spec doesn't help if our two major
operating systems don't follow the spec, plus the example doesn't work
on Win32 at all.

---

From: Tom Lane <[email-masked]>
Date: Wed, 06 Dec 2006 10:17:54 -0500

> very clear unless you are looking at the SGML.

No, you've completely misunderstood the original example.  It's
intending to show a backslash-backslash terminator for the \x command,
not two lines of input, ie the equivalent of this:

regression=# \x \\ select 1,2;
Expanded display is on.
-[ RECORD 1 ]
?column? | 1
?column? | 2

			regards, tom lane

---

From: Bruno Wolff III <[email-masked]>
Date: Wed, 6 Dec 2006 09:26:46 -0600

On Wed, Dec 06, 2006 at 09:14:01 -0500,
> operating systems don't follow the spec, plus the example doesn't work

If you need several lines of output, couldn't you use one echo for each
line and separate them with semicolons?

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 6 Dec 2006 10:39:34 -0500 (EST)

> regression=# \x \\ select 1,2;

You are right, I totally misunderstood it.  New patch applied, that
mentions \\ is a separator meta-command.  I now see \\ documented
farther down the file.  I didn't know it did that.

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/ref/psql-ref.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v
retrieving revision 1.176
diff -c -c -r1.176 psql-ref.sgml
*** doc/src/sgml/ref/psql-ref.sgml	5 Dec 2006 17:40:55 -0000	1.176
--- doc/src/sgml/ref/psql-ref.sgml	6 Dec 2006 15:37:30 -0000
***************
*** 87,95 ****
        it contains no <application>psql</application> specific features),
        or a single backslash command. Thus you cannot mix
        <acronym>SQL</acronym> and <application>psql</application>
!       meta-commands. To achieve that, you could pipe the string into
!       <application>psql</application>, like this: <literal>echo -e
!       "\\x\nSELECT * FROM foo;" | psql</literal>.
        </para>
        <para>
         If the command string contains multiple SQL commands, they are
--- 87,96 ----
        it contains no <application>psql</application> specific features),
        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>.
!       (<literal>\\</> is the separator meta-command.)
        </para>
        <para>
         If the command string contains multiple SQL commands, they are

---

From: Tom Lane <[email-masked]>
Date: Wed, 06 Dec 2006 10:42:05 -0500

> !       this: <literal>echo "\x \\ SELECT * FROM foo;" | psql</literal>.

This should probably use single quotes not double, hm?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 6 Dec 2006 10:46:56 -0500 (EST)

> This should probably use single quotes not double, hm?

Yep, done.

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/ref/psql-ref.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v
retrieving revision 1.177
diff -c -c -r1.177 psql-ref.sgml
*** doc/src/sgml/ref/psql-ref.sgml	6 Dec 2006 15:40:11 -0000	1.177
--- doc/src/sgml/ref/psql-ref.sgml	6 Dec 2006 15:46:30 -0000
***************
*** 89,95 ****
        <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>.
        (<literal>\\</> is the separator meta-command.)
        </para>
        <para>
--- 89,95 ----
        <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>.
        (<literal>\\</> is the separator meta-command.)
        </para>
        <para>