Hi,
If you want to check a GUC description, you access the "Server Configuration"
chapter and then need to figure out what is the exact section. Sometimes you
need a back-and-forth until find the exact GUC. You can click on the section
19.X and then browse to find the GUC. I was wondering if there is a better (and
fast) way to find a GUC. I experimented 2 approaches (see screenshots): (a) add
the GUCs to the "Reference" part and (b) add an appendix with all GUCs. The
idea is a page that list all GUCs in alphabetic order with a link that points
to the detailed description into "Server Configuration" chapter.
The natural choice is "Reference" part because it is more-or-less the proposal:
list of GUCs with links. However, the structure of it requires one HTML/man
page per GUC (even if you suppress the man generation, it would add 424 chunked
HTML files, each containing a single link to the detailed description). That's
an unavoidable cost of putting the GUC in the "Reference" ToC and that's why I
tried the option (b) whose approach is a list in a single page.
I thought about converting the "Server Configuration" chapter into a
"Reference" part. The 2 main cons are (a) increase the number of HTML/man files
(+400) and (b) each section may contain additional contents (before and after
the detailed GUC description) that apply to a set of GUCs.
I'm attaching option (b) that adds a new Appendix page ("PostgreSQL
Parameters"). It serves as a list of all GUCs with link directly to the
detailed description into "Server Configuration" chapter. The list is generated
at build time using a Perl script that avoids maintenance cost. I added this
new page as the first item in the Appendix mainly because of its importance.
--
Euler Taveira
EDB https://www.enterprisedb.com/From feae5d03fd66884c98a320fc3a1aaa9a52a48ea7 Mon Sep 17 00:00:00 2001
From: Euler Taveira <[email protected]>
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 <varlistentry>
elements with a "guc-" id, so it stays in sync with the documentation.
Entries that only describe possible values of a parameter use a
<literal> term instead of a <varname> 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 @@
<!ENTITY errcodes SYSTEM "errcodes.sgml">
<!ENTITY features SYSTEM "features.sgml">
<!ENTITY keywords SYSTEM "keywords.sgml">
+<!ENTITY parameters SYSTEM "parameters.sgml">
<!ENTITY sourcerepo SYSTEM "sourcerepo.sgml">
<!ENTITY release SYSTEM "release.sgml">
@@ -196,6 +197,7 @@
<!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
<!ENTITY errcodes-table SYSTEM "errcodes-table.sgml">
+<!ENTITY guc-list SYSTEM "guc-list.sgml">
<!ENTITY keywords-table SYSTEM "keywords-table.sgml">
<!-- back matter -->
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
+# <varlistentry> whose id starts with "guc-". The parameter name is taken from
+# the <varname> at the start of the <term>, 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
+# <literal> term instead of a <varname> 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{<varlistentry\s+id="(guc-[^"]*)"[^>]*>\s*<term>\s*<varname>([^<]+)</varname>}sg
+ )
+{
+ $ids{$2} = $1;
+}
+
+print "<!-- autogenerated by generate-guc-list.pl, do not edit -->\n";
+print "<simplelist>\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
+ " <member><link linkend=\"$ids{$name}\"><varname>$name</varname></link></member>\n";
+}
+print "</simplelist>\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 @@
+<!-- doc/src/sgml/parameters.sgml -->
+
+<appendix id="postgresql-conf">
+ <title>PostgreSQL Parameters</title>
+
+ <indexterm zone="postgresql-conf">
+ <primary>postgresql.conf</primary>
+ </indexterm>
+
+ <para>
+ The following configuration parameters can be set in
+ <filename>postgresql.conf</filename>. Each one links to its detailed
+ description in <xref linkend="runtime-config"/>; a few are read-only or
+ computed and cannot be changed by editing the file.
+ </para>
+
+ &guc-list;
+
+</appendix>
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.
<part id="appendixes">
<title>Appendixes</title>
+ ¶meters;
&errcodes;
&datetime;
&keywords;
--
2.39.5
