Re: Trivial doc patch

[rir]

On Sat, Oct 16, 2021 at 11:14:46AM +0900, Michael Paquier wrote:
> On Fri, Oct 15, 2021 at 01:13:14PM -0400, rir wrote:
> > This removes the outer square brackets in the create_database.sgml
> > file's synopsis.  In the command sysopses, this is the only case
> > where an optional group contains only optional groups.
> >
> >  CREATE DATABASE name
> > -[ [ WITH ] [ OWNER [=]  > class="parameter">user_name ]
> > +[ WITH ] [ OWNER [=]  > class="parameter">user_name ]
> > [...]
> > -   [ IS_TEMPLATE [=]  > class="parameter">istemplate ] ]
> > +   [ IS_TEMPLATE [=]  > class="parameter">istemplate ]
> >  
> >   
> 
> You are not wrong, and the existing doc is not wrong either.  I tend
> to prefer the existing style, though, as it insists on the options
> as being a single group, with or without the keyword WITH.

Michael, perhaps I mistake you; it seems you would like it better with
the extra '[' before OWNER.  That would more accurately point up

CREATE DATABASE name WITH;

Either way, my argument would have the basis.

In what sense are the options a single group?  That they all might
follow the 'WITH' is expressed without the duplicated brackets.
That the extra braces promote readability relies on an assumption or
knowledge of the command.

Given that 'optional, optional' has no independent meaning from
'optional';  it requires one to scan the entire set looking for
the non-optional embedded in the option.  So no gain.

Rob

Trivial doc patch

[rir]

This removes the outer square brackets in the create_database.sgml
file's synopsis.  In the command sysopses, this is the only case
where an optional group contains only optional groups.

Rob
>From dc59127d1a739e6de0cff20086baf47d15837f0b Mon Sep 17 00:00:00 2001
From: rir 
Date: Fri, 15 Oct 2021 11:29:26 -0400
Subject: [PATCH] Remove the only [optional] in synopses with [only optionals
 in it].

---
 doc/src/sgml/ref/create_database.sgml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 41cb4068ec..ec831bb57f 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -22,7 +22,7 @@ PostgreSQL documentation
  
 
 CREATE DATABASE name
-[ [ WITH ] [ OWNER [=] user_name ]
+[ WITH ] [ OWNER [=] user_name ]
[ TEMPLATE [=] template ]
[ ENCODING [=] encoding ]
[ LOCALE [=] locale ]
@@ -31,7 +31,7 @@ CREATE DATABASE name
[ TABLESPACE [=] tablespace_name ]
[ ALLOW_CONNECTIONS [=] allowconn ]
[ CONNECTION LIMIT [=] connlimit ]
-   [ IS_TEMPLATE [=] istemplate ] ]
+   [ IS_TEMPLATE [=] istemplate ]
 
  
 
-- 
2.20.1

Doc patch

[rir]

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:




Thanks for the software,
Rob
>From 711a3299851cde9ce00b5ff2962f20cdc1796e72 Mon Sep 17 00:00:00 2001
From: rir 
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
  FETCH
 
 
-FETCH  direction { FROM | IN }  cursor INTO target;
+FETCH  direction   FROM | IN  cursor INTO target;
 
 
 
@@ -3399,7 +3399,7 @@ FETCH RELATIVE -2 FROM curs4 INTO x;
  MOVE
 
 
-MOVE  direction { FROM | IN }  cursor;
+MOVE  direction   FROM | IN  cursor;
 
 
 
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
  
 
 
-FETCH [ direction [ FROM | IN ] ] cursor_name
+FETCH [ direction ] [ FROM | IN ] cursor_name
 
-where direction can be empty or one of:
+where direction can one of:
 
 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
  
 
 
-MOVE [ direction [ FROM | IN ] ] cursor_name
+MOVE [ direction ] [ FROM | IN ] cursor_name
 
-where direction can be empty or one of:
+where direction can one of:
 
 NEXT
 PRIOR
-- 
2.20.1