Date: Mon, 3 Nov 2025 21:06:44 +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: <32882add-b671-42db-a041-e2c2c5b7c315@ewie.name>
References: <a5034028-3f97-4157-8fd2-6eb552ffaab8@app.fastmail.com>
 <0a9d7393-1cf2-4d38-a648-631c1f93e345@ewie.name>
 <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>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="msbjuniwlqa4qqft"
Content-Disposition: inline
In-Reply-To: 
 <CAApHDvoqh_K2KTocwWYrGw5vLubnPnTzd1SvYTTonQ=vUXP7Ug@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/32882add-b671-42db-a041-e2c2c5b7c315%40ewie.name>
Precedence: bulk


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

On 2025-10-31 04:03 +0100, David Rowley wrote:
> On Fri, 31 Oct 2025 at 13:53, Erik Wienhold <ewie@ewie.name> wrote:
> > But I also agree with Tom that keeping a consistent style is impossible
> > in the long run.  But it also shows that the docs are still written by
> > humans.  As long as we can keep a consistent style within a single
> > listing (or even an entire page) I'm satisfied as a reader.
> 
> For me, I don't see this as a reason not to try. If we do get things
> to a consistent point, then anyone making changes that reference
> existing portions of the documentation for inspiration should maintain
> consistency. If we're entirely random, then there's no hope for anyone
> to figure out what the best practice or perfected casing is.

Sure.  I didn't say we shouldn't try.  But from my experience, minor
formatting issues slip through all the time if you can't rely on an
autoformatter or linter.  Maybe less so in these docs because the sample
queries are usually short.  But it already took me a couple of rounds to
find every lowercase keyword so far and I guess I still missed some.

> > Besides that I've fixed a couple of more places that had lowercase
> > keywords or were missing some whitespace that I had missed before.
> 
> A couple of things.
> 
> 1) I see you've added a space after "INSERT INTO table" and before the
> column list, but not consistently, per:
> 
> git grep -E "INSERT INTO \w+\("

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.

> 2) An identifier casing has been changed here:
> 
> -SELECT sub_part, SUM(quantity) as total_quantity
> +SELECT sub_part, sum(quantity) AS total_quantity

Reverted back to uppercase SUM.  I think this was the only changed
identifier and what remains should only be keyword and whitespace
changes to keep the patch focused on that.

> You could also look at the results of the SQL command that's returned
> by the following SQL to see if there's anything else. I do see some
> "ROLLUP(", "EXISTS(", "GROUPING(" and "VALUES(" in there. You have
> been changing "VALUES(" to "VALUES (", so I assume those ones have
> been missed:
> 
> select 'git grep -E "\b(' || string_agg(UPPER(word),'|') || ')\("'
> from pg_get_keywords();

Thanks.  Fixed those as well.  But only for keywords with non-C catcodes
because I figured that the catcode C keywords mostly cover builtin
function names where extra whitespace before the opening paren doesn't
make sense.  Missed the uppercase keywords before because I was only
searching for the lowercase ones.

-- 
Erik Wienhold

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