Date: Fri, 31 Oct 2025 01:52:48 +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: <0a68a965-4599-4af1-a1eb-bd8e1be75788@ewie.name>
References: <82eb512b-8ed2-46be-b311-54ffd26978c4@ewie.name>
 <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>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="chxid222hywahboc"
Content-Disposition: inline
In-Reply-To: 
 <CAApHDvqR+_EU0mxrmS-AieE_8ovqtmnsJSOk-oq-Rdk3JzNWOg@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/0a68a965-4599-4af1-a1eb-bd8e1be75788%40ewie.name>
Precedence: bulk


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

On 2025-10-29 22:24 +0100, David Rowley wrote:
> On Thu, 30 Oct 2025 at 09:48, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >
> > Bruce Momjian <bruce@momjian.us> writes:
> > > On Tue, Oct 28, 2025 at 04:34:45PM -0500, Nathan Bossart wrote:
> > >> I noticed the patch also changes some column types to lowercase:
> > >> ...
> > >> -    category_N TEXT
> > >> +    category_N text
> > >>
> > >> FWIW I tend to use uppercase for those, too, but I'm not sure there is a
> > >> preferred style for the docs.
> >
> > > Agreed, uppercase is better for type names.
> >
> > "text" is not a keyword according to either us or the SQL standard.
> > I agree that there's some reason to capitalize things that are
> > grammar keywords, such as INTEGER or VARCHAR, but it's a big stretch
> > to go from that to capitalizing everything that is a type name.
> > Would you capitalize user-defined type names?
> 
> Going by: git grep -i "\btext\b," we're fairly consistently using
> lower case, so FWIW, when I looked, I thought Eric's change made
> sense.

That is also my impression.  The docs clearly favor lowercase
identifiers and the various data type subpages consistently introduce
types as lowercase names.  Also, if you check the output of
format_type() or pg_get_viewdef() you'll see that we use lowercase
types names there as well, even for the ones mandated by the SQL
standard:

	regress=> CREATE VIEW myview AS SELECT 'foo'::VARCHAR AS f1;
	CREATE VIEW
	regress=> SELECT pg_get_viewdef('myview');
	             pg_get_viewdef
	-----------------------------------------
	  SELECT 'foo'::character varying AS f1;
	(1 row)

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.

> How about if Eric just drops the portion of the patch that alters the
> casing of the types and leaves all the keyword uppercasing stuff in.
> Any objections to that part?

In the attached v3 I've reverted that part (and other similar changes
that I had already in the pipeline after my OCD kicked in ;).  With one
exception: datatype.sgml has this change because lowercase bit(3) is
already used in the same listing a couple of lines down:

-CREATE TABLE test (a BIT(3), b BIT VARYING(5));
+CREATE TABLE test (a bit(3), b bit varying(5));

That's the only listing with inconsistently cased type names I could
find.

Besides that I've fixed a couple of more places that had lowercase
keywords or were missing some whitespace that I had missed before.

-- 
Erik Wienhold

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