Re: Doc patch

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(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Indecision is a decision. Inaction is an action. Mark Batterson