Date: Thu, 23 Oct 2025 23:39:17 +0300
From: Erik Wienhold <ewie@ewie.name>
To: Euler Taveira <euler@eulerto.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Use uppercase keywords in foreign key tutorial
Message-ID: <0a9d7393-1cf2-4d38-a648-631c1f93e345@ewie.name>
References: <82eb512b-8ed2-46be-b311-54ffd26978c4@ewie.name>
 <a5034028-3f97-4157-8fd2-6eb552ffaab8@app.fastmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="azr3km4zebrd3uiq"
Content-Disposition: inline
In-Reply-To: <a5034028-3f97-4157-8fd2-6eb552ffaab8@app.fastmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/0a9d7393-1cf2-4d38-a648-631c1f93e345%40ewie.name>
Precedence: bulk


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

On 2025-10-21 04:37 +0300, Euler Taveira wrote:
> On Thu, Oct 16, 2025, at 5:37 AM, Erik Wienhold wrote:
> > While browsing the docs I saw that the foreign key tutorial [1] uses
> > some lowercase keywords which are inconsistent with the rest of the
> > docs.  The attached patch fixes that.  Should be pushed to all stable
> > branches.
> >
> 
> Register your patch in the next CF [1] so it won't be forgotten.

https://commitfest.postgresql.org/patch/6159/

> These are not the only places that SQL keywords use lowercase. There
> are various cases (I searched for 'primary key') in dml.sgml,
> logicaldecoding.sgml, plpgsql.sgml, sepgsql.sgml, and textsearch.sgml
> that you should address as part of your proposal. I don't think there
> is an easy way to collect all cases. I also checked the most common
> keywords and I found a few lowercase cases. The SQL commands are
> usually inside programlisting tag so I tried the following command (to
> find the occurrence in the first line):
> 
> cd doc/srg/sgml
> grep -r -A 1 '<programlisting' * | grep -E 'create |alter |drop |select |insert into|update |delete '
> 
> (This command was an easy way to show there are other cases. It is not
> intended to be a starting point to collect all cases.)
> 
> Of course, there are other cases too. For example, "between" in
> config.sgml is lowercase.
> 
> <programlisting>
> CREATE TABLE parent(key integer, ...);
> CREATE TABLE child1000(check (key between 1000 and 1999)) INHERITS(parent);
> CREATE TABLE child2000(check (key between 2000 and 2999)) INHERITS(parent);
> ...
> SELECT * FROM parent WHERE key = 2400;
> </programlisting>

Ah, thanks for the tip.  I figured that I can grep all defined keywords
using the keyword list in the repository with this Bash script:

	#!/usr/bin/env bash

	set -eu

	# Collect all defined keywords and turn them lowercase for searching
	kwfile=$(mktemp)
	( cat doc/src/sgml/keywords/*.txt | tr [:upper:] [:lower:] ;
	  sed -n 's/PG_KEYWORD("\(\w\+\)".*/\1/p' src/include/parser/kwlist.h
	) | sort | uniq > "$kwfile"

	find_lowercase_keywords() {
		local infile="$1"
		# Extract program listings and prefix lines with line numbers of the
		# input file (filename gets prepended after grepping the keywords).
		# This also covers non-SQL program listings because there's no language
		# attribute that we could filter by.
		awk '/<programlisting/ {flag=1} flag {print NR "\t" $0} /<\/programlisting/ {flag=0}' "$infile"\
			| sed 's/--.*//'\
			| grep --color=always -Fw -f "$kwfile"\
			| sed "s@.*@$infile:&@"
	}

	for f in $(find doc/src/sgml -name '*.sgml'); do
		find_lowercase_keywords "$f"
	done

This of course produces a lot of noise, but I managed to find and fix a
couple more places with the attached v2 (including the ones you've
listed) that I've missed previously.  I've searched for "primary key"
across the docs previously but did not spot the matches between the
false-positive ones from the running text.

-- 
Erik Wienhold

--azr3km4zebrd3uiq
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment;
	filename="v2-0001-doc-Consistently-use-uppercase-keywords.patch"