pg.ddx.io pgsql-hackers@postgresql.org mailing list archive
help / color / mirror / Atom feedTrivial doc patch
5+ messages / 3 participants
[nested] [flat]
Commits from this thread:
2022-08-31 349baa87ae ba01810246 cdb836cc2d d07eecdce3 6a6edc0c8b 3da5ecb98c c1f54eac3a doc: simplify WITH clause syntax in CREATE DATABASE
* Trivial doc patch
@ 2021-10-15 17:13 rir <rirans@comcast.net>
0 siblings, 1 reply; 5+ messages in thread
From: rir @ 2021-10-15 17:13 UTC (permalink / raw)
To: pgsql-hackers@lists.postgresql.org
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
Attachments:
opt.patch (text/x-diff, 1.6K) download
From dc59127d1a739e6de0cff20086baf47d15837f0b Mon Sep 17 00:00:00 2001
From: rir <rirans@comcast.net>
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
<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> ]
[ LOCALE [=] <replaceable class="parameter">locale</replaceable> ]
@@ -31,7 +31,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable>
[ TABLESPACE [=] <replaceable class="parameter">tablespace_name</replaceable> ]
[ ALLOW_CONNECTIONS [=] <replaceable class="parameter">allowconn</replaceable> ]
[ CONNECTION LIMIT [=] <replaceable class="parameter">connlimit</replaceable> ]
- [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ] ]
+ [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ]
</synopsis>
</refsynopsisdiv>
--
2.20.1
* Re: Trivial doc patch
@ 2021-10-16 02:14 Michael Paquier <michael@paquier.xyz>
parent: rir <rirans@comcast.net>
0 siblings, 1 reply; 5+ messages in thread
From: Michael Paquier @ 2021-10-16 02:14 UTC (permalink / raw)
To: rir <rirans@comcast.net>; +Cc: pgsql-hackers@lists.postgresql.org
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
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Trivial doc patch
@ 2021-10-16 17:11 rir <rirans@comcast.net>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 1 reply; 5+ messages in thread
From: rir @ 2021-10-16 17:11 UTC (permalink / raw)
To: pgsql-hackers@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Trivial doc patch
@ 2022-08-19 14:42 Bruce Momjian <bruce@momjian.us>
parent: rir <rirans@comcast.net>
0 siblings, 1 reply; 5+ messages in thread
From: Bruce Momjian @ 2022-08-19 14:42 UTC (permalink / raw)
To: rir <rirans@comcast.net>; +Cc: pgsql-hackers@lists.postgresql.org
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@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
Attachments:
database.diff (text/x-diff, 1.3K) download
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>
* Re: Trivial doc patch
@ 2022-08-31 21:09 Bruce Momjian <bruce@momjian.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 5+ messages in thread
From: Bruce Momjian @ 2022-08-31 21:09 UTC (permalink / raw)
To: rir <rirans@comcast.net>; +Cc: pgsql-hackers@lists.postgresql.org
On Fri, Aug 19, 2022 at 10:42:45AM -0400, Bruce Momjian wrote:
> > 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.
Backpatched to PG 10. Thanks.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2022-08-31 21:09 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2021-10-15 17:13 Trivial doc patch rir <rirans@comcast.net>
2021-10-16 02:14 ` Michael Paquier <michael@paquier.xyz>
2021-10-16 17:11 ` rir <rirans@comcast.net>
2022-08-19 14:42 ` Bruce Momjian <bruce@momjian.us>
2022-08-31 21:09 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox