Re: docs: Link to the correct protocol version inspection function

[Peter Eisentraut]

On 23.10.25 07:58, Shinya Kato wrote:

On Wed, Oct 22, 2025 at 6:42 PM Jelte Fennema-Nio  wrote:

The docs for max_protocol_version suggested PQprotocolVersion instead of
PQfullProtocolVersion to find out the exact protocol version. Since
PQprotocolVersion only returns the major protocol version that is bad
advice.


Nice catch! The patch looks good to me.


committed

Re: Documentation improvement patch

[Peter Eisentraut]

On 25.10.25 21:01, Oleg wrote:

Dear Daniel,

Thank you for your prompt feedback.

Attached, please find the updated documentation patch, which 
incorporates your suggestions from both the first and second rounds of 
review.


  ALTER_REPLICATION_SLOT class="parameter">slot_name ( class="parameter">option [, ...] )

   ALTER_REPLICATION_SLOT
  
  
   
-   Change the definition of a replication slot.
+   Changes the definition of a replication slot.

I think these are intentionally written in imperative style.  Compare 
the synopses of the main SQL commands: "change the definition of a 
domain" etc.


- First, define a PgStat_KindInfo that includes all
+ First, define PgStat_KindInfo that includes all

I think this change is incorrect.  You are being asked to define an 
instance of PgStat_KindInfo, not PgStat_KindInfo itself (which already 
exists).


The remaining changes look ok to me.

Re: Use uppercase keywords in foreign key tutorial

[Erik Wienhold]

On 2025-10-29 22:24 +0100, David Rowley wrote:
> On Thu, 30 Oct 2025 at 09:48, Tom Lane  wrote:
> >
> > Bruce Momjian  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
>From b8415e908d27ba0a76a7725ce61d083e21bd3bdf Mon Sep 17 00:00:00 2001
From: Erik Wienhold 
Date: Thu, 16 Oct 2025 10:30:21 +0200
Subject: [PATCH v3] 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/config.sgml |   6 +-
 doc/src/sgml/cube.sgml   |   8 +-
 doc/src/sgml/datatype.sgml   |   6 +-
 doc/src/sgml/datetime.sgml   |   6 +-
 doc/src/sgml/dblink.sgml |  26 +++---
 doc/src/sgml/ddl.sgml|  28 +++
 doc/src/sgml/dict-int.sgml   |   2 +-
 doc/src/sgml/dml.sgml|   2 +-
 doc/src/sgml/ecpg.sgml   |   2 +-
 doc/src/sgml/event-trigger.sgml  |   2 +-
 doc/src/sgml/func/func-binarystring.sgml |   4 +-
 doc/src/sgml/func/func-matching.sgml |   8 +-
 doc/src/sgml/func/func-srf.sgml  |   4 +-
 doc/src/sgml/hstore.sgml |   2 +-
 doc/src/sgml/indices.sgml|   6 +-
 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 |   4 +-
 doc/src/sgml/plpgsql.sgml|  46 +--
 doc/src/sgml/plpython.sgml   |   2 +-
 doc/src/sgml/pltcl.sgml  |   2 +-
 doc/src/sgml/queries.sgml|   4 +-
 doc/src/sgml/ref/alter_table.sgml|   2 +-
 doc/src/sgml/ref/alter_view.sgml |   4 +-
 doc/src/sgml/ref/create_function.sgml|   6 +-
 doc/src/sgml/ref/create_table.sgml   |  22 ++---
 doc/

Re: Use uppercase keywords in foreign key tutorial

[David Rowley]

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.

> 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+\("

2) An identifier casing has been changed here:

-SELECT sub_part, SUM(quantity) as total_quantity
+SELECT sub_part, sum(quantity) AS total_quantity

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();

David