Subject: psql's \h MOVE

From: Alvaro Herrera <[email-masked]>
Date: Fri, 01 Apr 2011 12:17:18 -0300

I just noticed that \h MOVE is particularly unhelpful:

	alvherre=# \h move
	Command:     MOVE
	Description: position a cursor
	Syntax:
	MOVE [ direction { FROM | IN } ] cursorname

The problem is that it doesn't specify what "direction" is.  The doc
text tells you to look into FETCH for details, but in \h you have to
guess.

We could fix this by including a note about fetch in the <synopsis>,
so that it'd look like this:

	alvherre=# \h move
	Command:     MOVE
	Description: position a cursor
	Syntax:
	MOVE [ direction [ FROM | IN ] ] cursor_name

	See FETCH for details on direction

This, of course, also appears in the HTML output.

This requires this simple patch:

--- a/doc/src/sgml/ref/move.sgml
+++ b/doc/src/sgml/ref/move.sgml
@@ -27,6 +27,8 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 MOVE [ <replaceable class="PARAMETER">direction</replaceable> [ FROM | IN ] ] <replaceable class="PARAMETER">cursor_name</replaceable>
+
+<phrase>See <command>FETCH</command> for details on <replaceable class="PARAMETER">direction</replaceable>.</phrase>
 </synopsis>
  </refsynopsisdiv>

Would anybody object to doing things this way?

The alternative I see is to expand the "direction" in the MOVE synopsis,
but it is repetitive and would require more maintenance should we ever
decide to change the possible directions.

-- 
Álvaro Herrera <[email-masked]>

---

From: Tom Lane <[email-masked]>
Date: Sat, 02 Apr 2011 12:53:08 -0400

> 	See FETCH for details on direction

-1 ... if this annoys you, just duplicate the definition of direction
from FETCH.

			regards, tom lane

---

From: Robert Haas <[email-masked]>
Date: Sun, 3 Apr 2011 20:37:39 -0400

> -1 ... if this annoys you, just duplicate the definition of direction

+1 for duplicating the definition.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

---

From: Alvaro Herrera <[email-masked]>
Date: Mon, 04 Apr 2011 12:11:11 -0400

> +1 for duplicating the definition.

Done that way.

(I'd like to have something like \h column_constraint for common stuff
in ALTER TABLE and CREATE TABLE, but that'll have to wait.)

-- 
Álvaro Herrera <[email-masked]>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support