Date: Sat, 16 Oct 2021 13:11:49 -0400
From: rir <rirans@comcast.net>
To: pgsql-hackers@lists.postgresql.org
Subject: Re: Trivial doc patch
Message-ID: <20211016171149.yaouvlw5kvux6dvk@localhost>
References: <20211015171314.p7v4vygabwhh7ihc@localhost>
 <YWo1lgOQ0P1eUqqC@paquier.xyz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <YWo1lgOQ0P1eUqqC@paquier.xyz>
User-Agent: NeoMutt/20180716
Archived-At: 
 <https://www.postgresql.org/message-id/20211016171149.yaouvlw5kvux6dvk%40localhost>
Precedence: bulk

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 <replaceable class="parameter">name</replaceable>
> > -    [ [ WITH ] [ OWNER [=] <replaceable class="parameter">user_name</replaceable> ]
> > +    [ WITH ] [ OWNER [=] <replaceable class="parameter">user_name</replaceable> ]
> > [...]
> > -           [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ] ]
> > +           [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ]
> >  </synopsis>
> >   </refsynopsisdiv>
> 
> 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