Doc patch
In pgsql-docs, this patch has been recommended to you.
Lacking consensus and so not included is the the deletion of
comments pointing between the ref/MOVE and FETCH files. These
were of the form:
<!-- Note the "direction" bit is also in ref/fetch.sgml -->
Thanks for the software,
Rob
Attachments:
empty.patchtext/x-diff; charset=us-asciiDownload
From 711a3299851cde9ce00b5ff2962f20cdc1796e72 Mon Sep 17 00:00:00 2001
From: rir <rirans@comcast.net>
Date: Wed, 29 Sep 2021 19:06:01 -0400
Subject: [PATCH] Correction to docs of FETCH and MOVE. "empty or" is unusual
and redundant in synopsis phrase. Fix syntax in synopses of FETCH and MOVE
for sql and plpgsql.
---
doc/src/sgml/plpgsql.sgml | 4 ++--
doc/src/sgml/ref/fetch.sgml | 4 ++--
doc/src/sgml/ref/move.sgml | 4 ++--
3 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 4cd4bcba80..1cadec3dc4 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3342,7 +3342,7 @@ BEGIN
<title><literal>FETCH</literal></title>
<synopsis>
-FETCH <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <replaceable>cursor</replaceable> INTO <replaceable>target</replaceable>;
+FETCH <optional> <replaceable>direction</replaceable> </optional> <optional> FROM | IN </optional> <replaceable>cursor</replaceable> INTO <replaceable>target</replaceable>;
</synopsis>
<para>
@@ -3399,7 +3399,7 @@ FETCH RELATIVE -2 FROM curs4 INTO x;
<title><literal>MOVE</literal></title>
<synopsis>
-MOVE <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <replaceable>cursor</replaceable>;
+MOVE <optional> <replaceable>direction</replaceable> </optional> <optional> FROM | IN </optional> <replaceable>cursor</replaceable>;
</synopsis>
<para>
diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml
index ec843f5684..5e19531742 100644
--- a/doc/src/sgml/ref/fetch.sgml
+++ b/doc/src/sgml/ref/fetch.sgml
@@ -27,9 +27,9 @@ PostgreSQL documentation
<refsynopsisdiv>
<!-- Note the "direction" bit is also in ref/move.sgml -->
<synopsis>
-FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] <replaceable class="parameter">cursor_name</replaceable>
+FETCH [ <replaceable class="parameter">direction</replaceable> ] [ FROM | IN ] <replaceable class="parameter">cursor_name</replaceable>
-<phrase>where <replaceable class="parameter">direction</replaceable> can be empty or one of:</phrase>
+<phrase>where <replaceable class="parameter">direction</replaceable> can one of:</phrase>
NEXT
PRIOR
diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml
index 4c7d1dca39..c4d859d7b0 100644
--- a/doc/src/sgml/ref/move.sgml
+++ b/doc/src/sgml/ref/move.sgml
@@ -27,9 +27,9 @@ PostgreSQL documentation
<refsynopsisdiv>
<!-- Note the "direction" bit is also in ref/fetch.sgml -->
<synopsis>
-MOVE [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] <replaceable class="parameter">cursor_name</replaceable>
+MOVE [ <replaceable class="parameter">direction</replaceable> ] [ FROM | IN ] <replaceable class="parameter">cursor_name</replaceable>
-<phrase>where <replaceable class="parameter">direction</replaceable> can be empty or one of:</phrase>
+<phrase>where <replaceable class="parameter">direction</replaceable> can one of:</phrase>
NEXT
PRIOR
--
2.20.1
On Fri, 2021-10-15 at 12:52 -0400, rir wrote:
In pgsql-docs, this patch has been recommended to you.
Lacking consensus and so not included is the the deletion of
comments pointing between the ref/MOVE and FETCH files. These
were of the form:<!-- Note the "direction" bit is also in ref/fetch.sgml -->
Just for context: the -docs thread that belongs to this is
https://www.postgr.es/m/20211001163938.ifg4ayrsjwd7r6zr%40localhost
Yours,
Laurenz Albe
On Fri, Oct 15, 2021 at 12:52:48PM -0400, rir wrote:
In pgsql-docs, this patch has been recommended to you.
Lacking consensus and so not included is the the deletion of
comments pointing between the ref/MOVE and FETCH files. These
were of the form:<!-- Note the "direction" bit is also in ref/fetch.sgml -->
Sorry, I am just looking at this patch.
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 4cd4bcba80..1cadec3dc4 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -3342,7 +3342,7 @@ BEGIN <title><literal>FETCH</literal></title><synopsis> -FETCH <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <replaceable>cursor</replaceable> INTO <replaceable>target</replaceable>; +FETCH <optional> <replaceable>direction</replaceable> </optional> <optional> FROM | IN </optional> <replaceable>cursor</replaceable> INTO <replaceable>target</replaceable>; </synopsis>
If you look at pl/plpgsql/src/pl_gram.y, you can see in
read_fetch_direction() and complete_direction() that a lot of work is
done to make sure FROM/IN appears (see check_FROM). Therefore, I think
the above change is incorrect. Yes, this doesn't match the backend
syntax, probably because of syntax requirements of the PL/pgSQL
language.
<synopsis> -MOVE <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <replaceable>cursor</replaceable>; +MOVE <optional> <replaceable>direction</replaceable> </optional> <optional> FROM | IN </optional> <replaceable>cursor</replaceable>; </synopsis>
Same above.
diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml index ec843f5684..5e19531742 100644 --- a/doc/src/sgml/ref/fetch.sgml +++ b/doc/src/sgml/ref/fetch.sgml @@ -27,9 +27,9 @@ PostgreSQL documentation <refsynopsisdiv> <!-- Note the "direction" bit is also in ref/move.sgml --> <synopsis> -FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] <replaceable class="parameter">cursor_name</replaceable> +FETCH [ <replaceable class="parameter">direction</replaceable> ] [ FROM | IN ] <replaceable class="parameter">cursor_name</replaceable>-<phrase>where <replaceable class="parameter">direction</replaceable> can be empty or one of:</phrase> +<phrase>where <replaceable class="parameter">direction</replaceable> can one of:</phrase>NEXT PRIOR diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml index 4c7d1dca39..c4d859d7b0 100644 --- a/doc/src/sgml/ref/move.sgml +++ b/doc/src/sgml/ref/move.sgml @@ -27,9 +27,9 @@ PostgreSQL documentation <refsynopsisdiv> <!-- Note the "direction" bit is also in ref/fetch.sgml --> <synopsis> -MOVE [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] <replaceable class="parameter">cursor_name</replaceable> +MOVE [ <replaceable class="parameter">direction</replaceable> ] [ FROM | IN ] <replaceable class="parameter">cursor_name</replaceable>-<phrase>where <replaceable class="parameter">direction</replaceable> can be empty or one of:</phrase> +<phrase>where <replaceable class="parameter">direction</replaceable> can one of:</phrase>
You are right about the above to changes. The existing syntax shows
FROM/IN is only possible if a direction is specified, while
src/parser/gram.y says that FROM/IN with no direction is supported.
I plan to apply this second part of the patch soon.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
On Fri, Aug 19, 2022 at 12:04:54PM -0400, Bruce Momjian wrote:
You are right about the above to changes. The existing syntax shows
FROM/IN is only possible if a direction is specified, while
src/parser/gram.y says that FROM/IN with no direction is supported.I plan to apply this second part of the patch soon.
Patch applied back to PG 10. Thanks for the research on this.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson