Date: Tue, 4 Nov 2025 01:04:38 +0100
From: Erik Wienhold <ewie@ewie.name>
To: David Rowley <dgrowleyml@gmail.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, Bruce Momjian <bruce@momjian.us>,
	Nathan Bossart <nathandbossart@gmail.com>, Euler Taveira <euler@eulerto.com>,
	pgsql-docs@lists.postgresql.org
Subject: Re: Use uppercase keywords in foreign key tutorial
Message-ID: <4487a138-c4d2-4b06-80b3-5afe7f8e5d82@ewie.name>
References: 
 <CAApHDvoLfa2UjGfoGfVL4b=g5VbFgscrLONuC3kKE9=VZeeN=Q@mail.gmail.com>
 <b8d76840-5927-40aa-b38e-8ccb685aea92@app.fastmail.com>
 <aQE29YG5pY4Cl8ym@nathan>
 <aQJ6UIrQeC6impXg@momjian.us>
 <2903384.1761770924@sss.pgh.pa.us>
 <CAApHDvqR+_EU0mxrmS-AieE_8ovqtmnsJSOk-oq-Rdk3JzNWOg@mail.gmail.com>
 <0a68a965-4599-4af1-a1eb-bd8e1be75788@ewie.name>
 <CAApHDvoqh_K2KTocwWYrGw5vLubnPnTzd1SvYTTonQ=vUXP7Ug@mail.gmail.com>
 <32882add-b671-42db-a041-e2c2c5b7c315@ewie.name>
 <CAApHDvraaZLdTm4XTLkgGhUwecpmNm1dOJMcEToak-Bh5742hQ@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="opexzftefkxmdzod"
Content-Disposition: inline
In-Reply-To: 
 <CAApHDvraaZLdTm4XTLkgGhUwecpmNm1dOJMcEToak-Bh5742hQ@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/4487a138-c4d2-4b06-80b3-5afe7f8e5d82%40ewie.name>
Precedence: bulk


--opexzftefkxmdzod
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On 2025-11-03 23:37 +0100, David Rowley wrote:
> On Tue, 4 Nov 2025 at 09:06, Erik Wienhold <ewie@ewie.name> wrote:
> > Fixed in the attached v4.  Except for one match in dblink.sgml that
> > is the sample output of dblink_build_sql_insert which actually omits
> > the space after the table name and VALUES keyword.
> 
> I went through all these and I think it's mostly good.

Thanks.

> However...
> 
> It seems strange to me that you've made so many changes to transform
> "CREATE TABLE foo(" into "CREATE TABLE foo (", but you've done the
> opposite for CREATE FUNCTION and CREATE PROCEDURE. Did you go with the
> majority rules here?

Yes, CREATE FUNCTION with an extra space after the name is the
exception.  On master I count 29 (w/ space) vs. 249 (w/o space) matches:

$ git grep -Ei 'create(\s+or\s+replace)?\s+(function|procedure)\s+\w+(\.\w+)?\s+\(' doc | wc -l
29
$ git grep -Ei 'create(\s+or\s+replace)?\s+(function|procedure)\s+\w+(\.\w+)?\(' doc | wc -l
249

I also see similar counts for CREATE TABLE, but with the
one-space-after-table-name variant being more common:

$ git grep -Ei 'create\s+table(\s+if\s+not\+sexists)?\s+\w+(\.\w+)?\s+\(' doc | wc -l
213
$ git grep -Ei 'create\s+table(\s+if\s+not\+sexists)?\s+\w+(\.\w+)?\(' doc | wc -l
34

The attached v5 fixes a couple of more places that I missed in v4.

> It just seems a bit hard to follow what the standard is being enforced
> here and if that's hard to understand now, what hope is there of
> people following that in the future?

I follow this rule/standard/convention which also matches what I already
find in most parts of the docs:

* No extra space for function calls, e.g.
  extract(YEAR FROM now())

* Extra space for everything else, e.g.
  VALUES (1, 2);
  CREATE TABLE foo ();

> I'm starting to wonder if adjusting the spacing here is a worthwhile
> change.

I think it's worth to have that consistency.  If the patch is too broad
I can of course limit it to the listings with inconsistent keyword
casing which is more less patch v2 plus some changes from v3 and later.

Or just fix the keywords for now to get that out of the way and deal
with the spacing in a separate patch/thread.

-- 
Erik Wienhold

--opexzftefkxmdzod
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment;
	filename="v5-0001-doc-Apply-consistent-formatting-to-sample-SQL-sta.patch"