Re: Trivial doc patch

On Sat, Oct 16, 2021 at 01:11:49PM -0400, rir wrote:
> 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.

I originally had the same reaction Michael Paquier did, that having one
big optional block is nice, but seeing that 'CREATE DATABASE name WITH'
actually works, I can see the point in having our syntax be accurate,
and removing the outer optional brackets now does seem like an
improvement to me.

Attached is the proposed change.

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

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