Add note that PREPARE TRANSACTION is for transaction managers, not

regular applications. Also add a comment pointing out that tab-complition
for PREPARE TRANSACTION is missing on purpose.

Author: hlinnaka

doc/src/sgml/ref/prepare_transaction.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.9 2009/04/23 00:23:45 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.10 2010/01/25 18:23:10 heikki Exp $
 PostgreSQL documentation
 -->
 
@@ -82,6 +82,15 @@ PREPARE TRANSACTION <replaceable class="PARAMETER">transaction_id</replaceable>
  <refsect1>
   <title>Notes</title>
 
+  <para>
+   <command>PREPARE TRANSACTION</> is not intended for use in applications
+   or interactive sessions. It's purpose is to allow an external
+   transaction manager to perform atomic global transactions across multiple
+   databases or other transactional resources. Unless you're writing a
+   transaction manager, you probably shouldn't be using <command>PREPARE
+   TRANSACTION</>.
+  </para>
+
   <para>
    This command must be used inside a transaction block. Use <xref
    linkend="sql-begin" endterm="sql-begin-title"> to start one.

src/bin/psql/tab-complete.c

@@ -3,7 +3,7 @@
  *
  * Copyright (c) 2000-2010, PostgreSQL Global Development Group
  *
- * $PostgreSQL: pgsql/src/bin/psql/tab-complete.c,v 1.191 2010/01/22 16:40:19 rhaas Exp $
+ * $PostgreSQL: pgsql/src/bin/psql/tab-complete.c,v 1.192 2010/01/25 18:23:09 heikki Exp $
  */
 
 /*----------------------------------------------------------------------
@@ -1882,6 +1882,11 @@ psql_completion(char *text, int start, int end)
 		COMPLETE_WITH_LIST(list_PREPARE);
 	}
 
+/*
+ * PREPARE TRANSACTION is missing on purpose. It's intended for transaction
+ * managers, not for manual use in interactive sessions.
+ */
+
 /* REASSIGN OWNED BY xxx TO yyy */
 	else if (pg_strcasecmp(prev_wd, "REASSIGN") == 0)
 		COMPLETE_WITH_CONST("OWNED");