From feae5d03fd66884c98a320fc3a1aaa9a52a48ea7 Mon Sep 17 00:00:00 2001 From: Euler Taveira Date: Mon, 29 Jun 2026 23:46:08 -0300 Subject: [PATCH v1] Add an appendix listing the configuration parameters Add a "PostgreSQL Parameters" appendix that lists every configuration parameter name, each linking to its detailed description in the runtime configuration chapter. The list is generated at build time from config.sgml by generate-guc-list.pl, which scans the elements with a "guc-" id, so it stays in sync with the documentation. Entries that only describe possible values of a parameter use a term instead of a and are skipped. --- doc/src/sgml/.gitignore | 1 + doc/src/sgml/Makefile | 5 +++- doc/src/sgml/filelist.sgml | 2 ++ doc/src/sgml/generate-guc-list.pl | 43 +++++++++++++++++++++++++++++++ doc/src/sgml/meson.build | 9 +++++++ doc/src/sgml/parameters.sgml | 19 ++++++++++++++ doc/src/sgml/postgres.sgml | 1 + 7 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 doc/src/sgml/generate-guc-list.pl create mode 100644 doc/src/sgml/parameters.sgml diff --git a/doc/src/sgml/.gitignore b/doc/src/sgml/.gitignore index 91f2781fe7b..7ba29be3d0e 100644 --- a/doc/src/sgml/.gitignore +++ b/doc/src/sgml/.gitignore @@ -14,6 +14,7 @@ /features-supported.sgml /features-unsupported.sgml /errcodes-table.sgml +/guc-list.sgml /keywords-table.sgml /targets-meson.sgml /version.sgml diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index b53b2694a6b..96efbd7147f 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -57,7 +57,7 @@ override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)' GENERATED_SGML = version.sgml \ features-supported.sgml features-unsupported.sgml errcodes-table.sgml \ - keywords-table.sgml targets-meson.sgml wait_event_types.sgml + guc-list.sgml keywords-table.sgml targets-meson.sgml wait_event_types.sgml ALL_SGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/func/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) @@ -106,6 +106,9 @@ features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_package errcodes-table.sgml: $(top_srcdir)/src/backend/utils/errcodes.txt generate-errcodes-table.pl $(PERL) $(srcdir)/generate-errcodes-table.pl $< > $@ +guc-list.sgml: config.sgml generate-guc-list.pl + $(PERL) $(srcdir)/generate-guc-list.pl $< > $@ + keywords-table.sgml: $(top_srcdir)/src/include/parser/kwlist.h $(wildcard $(srcdir)/keywords/sql*.txt) generate-keywords-table.pl $(PERL) $(srcdir)/generate-keywords-table.pl $(srcdir) > $@ diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 66ea8b988a1..d2fbcf82a2f 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -182,6 +182,7 @@ + @@ -196,6 +197,7 @@ + diff --git a/doc/src/sgml/generate-guc-list.pl b/doc/src/sgml/generate-guc-list.pl new file mode 100644 index 00000000000..dd0ffb05eec --- /dev/null +++ b/doc/src/sgml/generate-guc-list.pl @@ -0,0 +1,43 @@ +#!/usr/bin/perl +# +# Generate the list of configuration parameter names for the +# "PostgreSQL Parameters" appendix. +# +# Every configuration parameter is documented in config.sgml inside a +# whose id starts with "guc-". The parameter name is taken from +# the at the start of the , and the entry id is used to link +# each name to its detailed description. Entries that merely describe possible +# values of a parameter (such as the HIGH/MEDIUM groups of ssl_ciphers) use a +# term instead of a and are therefore skipped. +# +# Copyright (c) 2026, PostgreSQL Global Development Group + +use strict; +use warnings FATAL => 'all'; + +my $configfile = $ARGV[0]; + +open my $fh, '<', $configfile or die "could not open $configfile: $!"; +my $content = do { local $/; <$fh> }; +close $fh; + +my %ids; + +# Match each parameter (varlistentry tag) and capture the id and the varname. +while ($content =~ + m{]*>\s*\s*([^<]+)}sg + ) +{ + $ids{$2} = $1; +} + +print "\n"; +print "\n"; +# Sort case-insensitively so that mixed-case names (such as DateStyle) are +# ordered by their letters rather than by ASCII case. +foreach my $name (sort { lc($a) cmp lc($b) } keys %ids) +{ + print + " $name\n"; +} +print "\n"; diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build index 8517d837b78..91f775e006b 100644 --- a/doc/src/sgml/meson.build +++ b/doc/src/sgml/meson.build @@ -48,6 +48,15 @@ doc_generated += custom_target('errcodes-table.sgml', capture: true, ) +doc_generated += custom_target('guc-list.sgml', + input: files('config.sgml'), + output: 'guc-list.sgml', + command: [perl, files('generate-guc-list.pl'), '@INPUT@'], + build_by_default: false, + install: false, + capture: true, +) + doc_generated += custom_target('wait_event_types.sgml', input: files( '../../../src/backend/utils/activity/wait_event_names.txt'), diff --git a/doc/src/sgml/parameters.sgml b/doc/src/sgml/parameters.sgml new file mode 100644 index 00000000000..0143997e23b --- /dev/null +++ b/doc/src/sgml/parameters.sgml @@ -0,0 +1,19 @@ + + + + PostgreSQL Parameters + + + postgresql.conf + + + + The following configuration parameters can be set in + postgresql.conf. Each one links to its detailed + description in ; a few are read-only or + computed and cannot be changed by editing the file. + + + &guc-list; + + diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 2101442c90f..e60c9db67dc 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -271,6 +271,7 @@ break is not needed in a wider output rendering. Appendixes + ¶meters; &errcodes; &datetime; &keywords; -- 2.39.5