Re: Doc patch - Mailing list pgsql-hackers

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