Re: Use uppercase keywords in foreign key tutorial
On 2025-10-31 04:03 +0100, David Rowley wrote:
> On Fri, 31 Oct 2025 at 13:53, Erik Wienhold 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
>From 2262fb3fffb389d4f01d998e4882164c42c16af4 Mon Sep 17 00:00:00 2001
From: Erik Wienhold
Date: Thu, 16 Oct 2025 10:30:21 +0200
Subject: [PATCH v4] doc: Apply consistent formatting to sample SQL statements
Use uppercase SQL keywords consistently throughout the documentation to
ease reading. Also add a single space between keywords/names and tuples
which is a common convention, such as after keyword VALUES. Additional
whitespace is added in a couple of other places where it improves
readability.
---
doc/src/sgml/advanced.sgml | 4 +-
doc/src/sgml/bloom.sgml | 12 +--
doc/src/sgml/btree-gist.sgml | 8 +-
doc/src/sgml/charset.sgml| 4 +-
doc/src/sgml/config.sgml | 6 +-
doc/src/sgml/cube.sgml | 8 +-
doc/src/sgml/datatype.sgml | 18 ++--
doc/src/sgml/datetime.sgml | 6 +-
doc/src/sgml/dblink.sgml | 26 +++---
doc/src/sgml/ddl.sgml| 32
doc/src/sgml/dict-int.sgml | 2 +-
doc/src/sgml/dml.sgml| 2 +-
doc/src/sgml/ecpg.sgml | 10 +--
doc/src/sgml/event-trigger.sgml | 2 +-
doc/src/sgml/func/func-aggregate.sgml| 4 +-
doc/src/sgml/func/func-binarystring.sgml | 4 +-
doc/src/sgml/func/func-bitstring.sgml| 2 +-
doc/src/sgml/func/func-comparison.sgml | 4 +-
doc/src/sgml/func/func-comparisons.sgml | 2 +-
doc/src/sgml/func/func-json.sgml | 4 +-
doc/src/sgml/func/func-matching.sgml | 8 +-
doc/src/sgml/func/func-srf.sgml | 4 +-
doc/src/sgml/func/func-string.sgml | 8 +-
doc/src/sgml/func/func-subquery.sgml | 2 +-
doc/src/sgml/func/func-xml.sgml | 20 ++---
doc/src/sgml/hstore.sgml | 8 +-
doc/src/sgml/indices.sgml| 6 +-
doc/src/sgml/isn.sgml| 12 +--
doc/src/sgml/logical-replication.sgml| 36
doc/src/sgml/logicaldecoding.sgml| 24 +++---
doc/src/sgml/maintenance.sgml| 4 +-
doc/src/sgml/manage-ag.sgml | 4 +-
doc/src/sgml/monitoring.sgml | 4 +-
doc/src/sgml/pgcrypto.sgml | 2 +-
doc/src/sgml/pgstattuple.sgml| 2 +-
doc/src/sgm
Re: Use uppercase keywords in foreign key tutorial
On 2025-11-03 23:37 +0100, David Rowley wrote:
> On Tue, 4 Nov 2025 at 09:06, Erik Wienhold 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
>From bdece235734496b551fc0b826ffd199880cee5d2 Mon Sep 17 00:00:00 2001
From: Erik Wienhold
Date: Thu, 16 Oct 2025 10:30:21 +0200
Subject: [PATCH v5] doc: Apply consistent formatting to sample SQL statements
Use uppercase SQL keywords consistently throughout the documentation to
ease reading. Also add a single space between keywords/names and tuples
which is a common convention, such as after keyword VALUES. Additional
whitespace is added in a couple of other places where it improves
readability.
---
doc/src/sgml/advanced.sgml | 4 +-
doc/src/sgml/bloom.sgml | 12 +--
doc/src/sgml/btree-gist.sgml | 8 +-
doc/src/sgml/charset.sgml| 4 +-
doc/src/sgml/config.sgml | 6 +-
doc/src/sgml/cube.sgml | 8 +-
doc/src/sgml/datatype.sgml | 18 ++--
doc/src/sgml/datetime.sgml | 6 +-
doc/src/sgml/dblink.sgml | 26 +++---
doc/src/sgml/ddl.sgml| 32
doc/src/sgml/dict-int.sgml | 2 +-
doc/src/sgml/dml.sgml| 2 +-
doc/src/sgml/ecpg.sgml | 10 +--
doc/src/sgml/event-trigger.sgml | 4 +-
doc/src/sgml/func/func-aggregate.sgml| 4 +-
doc/src/sgml/func/func-binarystring.sgml | 4 +-
doc/src/sgml/func/func-bitstring.sgml| 2 +-
doc/src/sgml/func/func-comparison.sgml | 4 +-
doc/src/sgml/func/func-comparisons.sgml | 2 +-
doc/src/sgml/func/func-json.sgml | 4 +-
doc/src/sgml/func/func-matching.sgml | 8 +-
doc/src/sgml/func/func-srf.sgml | 4 +-
doc/src/sgml/func/func-string.sgml | 8 +-
doc/src/sgml/func/func-subquery.sgml | 2 +-
doc/src/sgml/func/func-xml.sgml | 20 ++---
doc/src/sgml/hstore.sgml | 8 +-
doc/src/sgml/indices.sgml| 6 +-
doc/src/sgml/intagg.sgml | 8 +-
doc/src/sgml/isn.sgml| 12 +--
doc/src/sgml/logical-replication.sgml| 36
doc/src/sgml/logicaldecoding.sgml| 24 +++---
doc/src/sgml/maintenance.sgml| 4 +-
doc/src/sgml/manage-ag.sgml | 4 +-
doc/src/sgml/monitoring.sgml | 4 +-
doc/src/sgml/pgcrypto.sgml | 2 +-
doc/src/sgml/pgstattuple.sgml| 2 +-
doc/src/sgml/pgsurgery.sgml | 12 +--
doc/src/sgml/planstats.sgml | 2 +-
doc/src/sgml/plperl.sgml | 10 +--
doc/src/sgml/plpgsql.sgml| 60 +++---
doc/src/sgml/plpython.sgml | 20 ++---
doc/src/sgml/pltcl.sgml | 2 +-
doc/src/sgml/protocol.sgml | 12 +--
doc/src/sgml/queries.sgml| 16 ++--
doc/src/sgml/r
Re: Feature request: Add a llms.txt file to the docs for AIs to learn
> On 2 Nov 2025, at 00:47, Adrián Cuadrado Chavarría > wrote: > > Some projects like [NextJS](https://nextjs.org/docs/llms-full.txt), > [Stripe](https://docs.stripe.com/llms.txt), > [BetterAuth](https://www.better-auth.com/llms.txt) and > [Zod](https://zod.dev/llms.txt) already provide this. > > With this file we can make sure that the AI model fetching it is always using > the latest features and versions of postgresql. > > https://llmstxt.org/ I would recommend posting this to the pgsql-www@ mailinglist instead to get the attention of the website team. That being said, AFAICT there are no LLM providers who have publicly stated that they are using this proposed standard at all, and the author has not submitted it to IETF for a formal review in the RFC process, so it doesn't seem all that promising. -- Daniel Gustafsson
Re: Use uppercase keywords in foreign key tutorial
On Tue, 4 Nov 2025 at 09:06, Erik Wienhold 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. 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? 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'm starting to wonder if adjusting the spacing here is a worthwhile change.
David
Re: Use uppercase keywords in foreign key tutorial
On Tue, 4 Nov 2025 at 13:04, Erik Wienhold wrote: > > On 2025-11-03 23:37 +0100, David Rowley wrote: > > 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. I think just the keyword upper casing is a good idea for now. I'm starting to lose hope that there's enough merit and consistency to the proposed whitespace changes. Maybe there's a subset of it that does make sense to do. David
