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 <br...@momjian.us> https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index 0b32e7ecf9..0ce0bd8a1a 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -22,7 +22,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> CREATE DATABASE <replaceable class="parameter">name</replaceable> - [ [ WITH ] [ OWNER [=] <replaceable class="parameter">user_name</replaceable> ] + [ WITH ] [ OWNER [=] <replaceable class="parameter">user_name</replaceable> ] [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ] [ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ] [ STRATEGY [=] <replaceable class="parameter">strategy</replaceable> ] ] @@ -36,7 +36,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> [ ALLOW_CONNECTIONS [=] <replaceable class="parameter">allowconn</replaceable> ] [ CONNECTION LIMIT [=] <replaceable class="parameter">connlimit</replaceable> ] [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ] - [ OID [=] <replaceable class="parameter">oid</replaceable> ] ] + [ OID [=] <replaceable class="parameter">oid</replaceable> ] </synopsis> </refsynopsisdiv>