describe special values in GUC descriptions more consistently

From 25f62fa18e5e6ffd0fbd48e9f9bdd5474caaf23c Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Fri, 7 Feb 2025 16:06:18 -0600
Subject: [PATCH v2 1/1] Describe special values in GUC descriptions more
 consistently.

---
 src/backend/utils/misc/guc_tables.c | 139 ++++++++++++++--------------
 1 file changed, 70 insertions(+), 69 deletions(-)

diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index ce7534d4d23..8dc8a912c19 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -2109,7 +2109,7 @@ struct config_int ConfigureNamesInt[] =
 		{"archive_timeout", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the amount of time to wait before forcing a "
 						 "switch to the next WAL file."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_S
 		},
 		&XLogArchiveTimeout,
@@ -2186,7 +2186,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_pool_size", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of individuals in the population."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_pool_size,
@@ -2196,7 +2196,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_generations", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of iterations of the algorithm."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_generations,
@@ -2219,7 +2219,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_archive_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_archive_delay,
@@ -2230,7 +2230,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_streaming_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_streaming_delay,
@@ -2263,7 +2263,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_receiver_timeout", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum wait time to receive data from the sending server."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&wal_receiver_timeout,
@@ -2354,7 +2354,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"shared_memory_size_in_huge_pages", PGC_INTERNAL, PRESET_OPTIONS,
 			gettext_noop("Shows the number of huge pages needed for the main shared memory area."),
-			gettext_noop("-1 indicates that the value could not be determined."),
+			gettext_noop("-1 means the value could not be determined."),
 			GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE | GUC_RUNTIME_COMPUTED
 		},
 		&shared_memory_size_in_huge_pages,
@@ -2376,7 +2376,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"commit_timestamp_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the commit timestamp cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&commit_timestamp_buffers,
@@ -2431,7 +2431,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"subtransaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the subtransaction cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&subtransaction_buffers,
@@ -2442,7 +2442,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the transaction status cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&transaction_buffers,
@@ -2626,7 +2626,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_vacuum_cost_limit", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost amount available before napping, for autovacuum."),
-			NULL
+			gettext_noop("-1 means use \"vacuum_cost_limit\".")
 		},
 		&autovacuum_vac_cost_limit,
 		-1, -1, 10000,
@@ -2682,7 +2682,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"statement_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any statement."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&StatementTimeout,
@@ -2693,7 +2693,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"lock_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any wait for a lock."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&LockTimeout,
@@ -2704,7 +2704,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_in_transaction_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleInTransactionSessionTimeout,
@@ -2715,7 +2715,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any transaction within a session (not a prepared transaction)."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&TransactionTimeout,
@@ -2726,7 +2726,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when not in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleSessionTimeout,
@@ -2940,7 +2940,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Write a message to the server log if checkpoints "
 						 "caused by the filling of WAL segment files happen more "
 						 "frequently than this amount of time. "
-						 "Zero turns off the warning."),
+						 "0 disables the warning."),
 			GUC_UNIT_S
 		},
 		&CheckPointWarning,
@@ -2951,7 +2951,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"checkpoint_flush_after", PGC_SIGHUP, WAL_CHECKPOINTS,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&checkpoint_flush_after,
@@ -2962,7 +2962,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_buffers", PGC_POSTMASTER, WAL_SETTINGS,
 			gettext_noop("Sets the number of disk-page buffers in shared memory for WAL."),
-			gettext_noop("Specify -1 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("-1 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_XBLOCKS
 		},
 		&XLOGbuffers,
@@ -3029,7 +3029,8 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the maximum WAL size that can be reserved by replication slots."),
 			gettext_noop("Replication slots will be marked as failed, and segments released "
 						 "for deletion or recycling, if this much space is occupied by WAL "
-						 "on disk."),
+						 "on disk. "
+						 "-1 means no maximum."),
 			GUC_UNIT_MB
 		},
 		&max_slot_wal_keep_size_mb,
@@ -3089,7 +3090,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the minimum execution time above which "
 						 "a sample of statements will be logged."
 						 " Sampling is determined by \"log_statement_sample_rate\"."),
-			gettext_noop("Zero logs a sample of all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables sampling. 0 means sample all statements."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_sample,
@@ -3101,7 +3102,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_min_duration_statement", PGC_SUSET, LOGGING_WHEN,
 			gettext_noop("Sets the minimum execution time above which "
 						 "all statements will be logged."),
-			gettext_noop("Zero prints all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables logging statement durations. 0 means log all statement durations."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_statement,
@@ -3113,7 +3114,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_autovacuum_min_duration", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Sets the minimum execution time above which "
 						 "autovacuum actions will be logged."),
-			gettext_noop("Zero prints all actions. -1 turns autovacuum logging off."),
+			gettext_noop("-1 disables logging autovacuum actions. 0 means log all autovacuum actions."),
 			GUC_UNIT_MS
 		},
 		&Log_autovacuum_min_duration,
@@ -3125,7 +3126,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length,
@@ -3137,7 +3138,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length_on_error", PGC_USERSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements, on error."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length_on_error,
@@ -3159,7 +3160,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_lru_maxpages", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Background writer maximum number of LRU pages to flush per round."),
-			NULL
+			gettext_noop("0 disables background writing.")
 		},
 		&bgwriter_lru_maxpages,
 		100, 0, INT_MAX / 2,	/* Same upper limit as shared_buffers */
@@ -3169,7 +3170,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_flush_after", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&bgwriter_flush_after,
@@ -3182,7 +3183,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_ASYNCHRONOUS,
 			gettext_noop("Number of simultaneous requests that can be handled efficiently by the disk subsystem."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&effective_io_concurrency,
@@ -3196,7 +3197,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_ASYNCHRONOUS,
 			gettext_noop("A variant of \"effective_io_concurrency\" that is used for maintenance work."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&maintenance_io_concurrency,
@@ -3223,7 +3224,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"backend_flush_after", PGC_USERSET, RESOURCES_ASYNCHRONOUS,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&backend_flush_after,
@@ -3283,7 +3284,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_age", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the amount of time to wait before forcing "
 						 "log file rotation."),
-			NULL,
+			gettext_noop("0 disables time-based creation of new log files."),
 			GUC_UNIT_MIN
 		},
 		&Log_RotationAge,
@@ -3295,7 +3296,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_size", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the maximum size a log file can reach before "
 						 "being rotated."),
-			NULL,
+			gettext_noop("0 disables size-based creation of new log files."),
 			GUC_UNIT_KB
 		},
 		&Log_RotationSize,
@@ -3397,7 +3398,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_summary_keep_time", PGC_SIGHUP, WAL_SUMMARIZATION,
 			gettext_noop("Time for which WAL summary files should be kept."),
-			NULL,
+			gettext_noop("0 disables automatic summary file deletion."),
 			GUC_UNIT_MIN,
 		},
 		&wal_summary_keep_time,
@@ -3428,8 +3429,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_max_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum, or -1 to disable maximum threshold."),
-			NULL
+			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum."),
+			gettext_noop("-1 disables the maximum threshold.")
 		},
 		&autovacuum_vac_max_thresh,
 		100000000, -1, INT_MAX,
@@ -3437,8 +3438,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_insert_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Minimum number of tuple inserts prior to vacuum, or -1 to disable insert vacuums."),
-			NULL
+			gettext_noop("Minimum number of tuple inserts prior to vacuum."),
+			gettext_noop("-1 disables insert vacuums.")
 		},
 		&autovacuum_vac_ins_thresh,
 		1000, -1, INT_MAX,
@@ -3530,7 +3531,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_work_mem", PGC_SIGHUP, RESOURCES_MEM,
 			gettext_noop("Sets the maximum memory to be used by each autovacuum worker process."),
-			NULL,
+			gettext_noop("-1 means use \"maintenance_work_mem\"."),
 			GUC_UNIT_KB
 		},
 		&autovacuum_work_mem,
@@ -3541,7 +3542,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_idle", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between issuing TCP keepalives."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_idle,
@@ -3552,7 +3553,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between TCP keepalive retransmits."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_interval,
@@ -3575,8 +3576,8 @@ struct config_int ConfigureNamesInt[] =
 		{"tcp_keepalives_count", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Maximum number of TCP keepalive retransmits."),
 			gettext_noop("Number of consecutive keepalive retransmits that can be "
-						 "lost before a connection is considered dead. A value of 0 uses the "
-						 "system default."),
+						 "lost before a connection is considered dead. "
+						 "0 means use the system default."),
 		},
 		&tcp_keepalives_count,
 		0, 0, INT_MAX,
@@ -3586,8 +3587,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"gin_fuzzy_search_limit", PGC_USERSET, CLIENT_CONN_OTHER,
 			gettext_noop("Sets the maximum allowed result for exact search by GIN."),
-			NULL,
-			0
+			gettext_noop("0 means no limit."),
 		},
 		&GinFuzzySearchLimit,
 		0, 0, INT_MAX,
@@ -3643,7 +3643,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"log_temp_files", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Log the use of temporary files larger than this number of kilobytes."),
-			gettext_noop("Zero logs all files. The default is -1 (turning this feature off)."),
+			gettext_noop("-1 disables temporary file logs. 0 means log all files."),
 			GUC_UNIT_KB
 		},
 		&log_temp_files,
@@ -3676,7 +3676,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_user_timeout", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("TCP user timeout."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_MS
 		},
 		&tcp_user_timeout,
@@ -3687,7 +3687,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"huge_page_size", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("The size of huge page that should be requested."),
-			NULL,
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_KB
 		},
 		&huge_page_size,
@@ -3698,7 +3698,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"debug_discard_caches", PGC_SUSET, DEVELOPER_OPTIONS,
 			gettext_noop("Aggressively flush system caches for debugging purposes."),
-			NULL,
+			gettext_noop("0 means use normal caching behavior."),
 			GUC_NOT_IN_SAMPLE
 		},
 		&debug_discard_caches,
@@ -3721,7 +3721,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"client_connection_check_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Sets the time interval between checks for disconnection while running queries."),
-			NULL,
+			gettext_noop("0 disables connection checks."),
 			GUC_UNIT_MS
 		},
 		&client_connection_check_interval,
@@ -3733,7 +3733,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_startup_progress_interval", PGC_SIGHUP, LOGGING_WHEN,
 			gettext_noop("Time between progress updates for "
 						 "long-running startup operations."),
-			gettext_noop("0 turns this feature off."),
+			gettext_noop("0 disables progress updates."),
 			GUC_UNIT_MS,
 		},
 		&log_startup_progress_interval,
@@ -3964,7 +3964,7 @@ struct config_real ConfigureNamesReal[] =
 	{
 		{"autovacuum_vacuum_cost_delay", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost delay in milliseconds, for autovacuum."),
-			NULL,
+			gettext_noop("-1 means use \"vacuum_cost_delay\"."),
 			GUC_UNIT_MS
 		},
 		&autovacuum_vac_cost_delay,
@@ -4055,7 +4055,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_library", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the library that will be called to archive a WAL file."),
-			gettext_noop("An empty string indicates that \"archive_command\" should be used.")
+			gettext_noop("An empty string means \"archive_command\" should be used.")
 		},
 		&XLogArchiveLibrary,
 		"",
@@ -4183,7 +4183,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"log_line_prefix", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Controls information prefixed to each log line."),
-			gettext_noop("If blank, no prefix is used.")
+			gettext_noop("An empty string means no prefix.")
 		},
 		&Log_line_prefix,
 		"%m [%p] ",
@@ -4226,7 +4226,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"default_tablespace", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the default tablespace to create tables and indexes in."),
-			gettext_noop("An empty string selects the database's default tablespace."),
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_IS_NAME
 		},
 		&default_tablespace,
@@ -4237,7 +4237,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"temp_tablespaces", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the tablespace(s) to use for temporary tables and sort files."),
-			NULL,
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_LIST_INPUT | GUC_LIST_QUOTE
 		},
 		&temp_tablespaces,
@@ -4249,7 +4249,7 @@ struct config_string ConfigureNamesString[] =
 		{"createrole_self_grant", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets whether a CREATEROLE user automatically grants "
 						 "the role to themselves, and with which options."),
-			NULL,
+			gettext_noop("An empty string disables automatic self grants."),
 			GUC_LIST_INPUT
 		},
 		&createrole_self_grant,
@@ -4285,7 +4285,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"bonjour_name", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the Bonjour service name."),
-			NULL
+			gettext_noop("An empty string means use the computer name.")
 		},
 		&bonjour_name,
 		"",
@@ -4295,7 +4295,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_messages", PGC_SUSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the language in which messages are displayed."),
-			NULL
+			gettext_noop("An empty string means use the system setting.")
 		},
 		&locale_messages,
 		"",
@@ -4305,7 +4305,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_monetary", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting monetary amounts."),
-			NULL
+			gettext_noop("An empty string means use the system setting.")
 		},
 		&locale_monetary,
 		"C",
@@ -4315,7 +4315,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_numeric", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting numbers."),
-			NULL
+			gettext_noop("An empty string means use the system setting.")
 		},
 		&locale_numeric,
 		"C",
@@ -4325,7 +4325,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_time", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting date and time values."),
-			NULL
+			gettext_noop("An empty string means use the system setting.")
 		},
 		&locale_time,
 		"C",
@@ -4504,7 +4504,8 @@ struct config_string ConfigureNamesString[] =
 		{"unix_socket_group", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the owning group of the Unix-domain socket."),
 			gettext_noop("The owning user of the socket is always the user "
-						 "that starts the server.")
+						 "that starts the server. "
+						 "An empty string means use the user's default group.")
 		},
 		&Unix_socket_group,
 		"",
@@ -4630,7 +4631,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_ca_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL certificate authority file."),
-			NULL
+			gettext_noop("An empty string disables client certificate validation.")
 		},
 		&ssl_ca_file,
 		"",
@@ -4640,7 +4641,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_crl_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL certificate revocation list file."),
-			NULL
+			gettext_noop("An empty string means don't load CRL file unless \"ssl_crl_dir\" is set.")
 		},
 		&ssl_crl_file,
 		"",
@@ -4650,7 +4651,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_crl_dir", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL certificate revocation list directory."),
-			NULL
+			gettext_noop("An empty string means don't use CRLs unless \"ssl_crl_file\" is set.")
 		},
 		&ssl_crl_dir,
 		"",
@@ -4681,7 +4682,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_tls13_ciphers", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites (leave blank for default)."),
-			NULL,
+			gettext_noop("An empty string means use the default cipher suites."),
 			GUC_SUPERUSER_ONLY
 		},
 		&SSLCipherSuites,
@@ -4722,7 +4723,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_dh_params_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL DH parameters file."),
-			NULL,
+			gettext_noop("An empty string means use compiled-in default parameters."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_dh_params_file,
@@ -4733,7 +4734,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_passphrase_command", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Command to obtain passphrases for SSL."),
-			NULL,
+			gettext_noop("An empty string means use the built-in prompting mechanism."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_passphrase_command,
@@ -4799,7 +4800,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"debug_io_direct", PGC_POSTMASTER, DEVELOPER_OPTIONS,
 			gettext_noop("Use direct I/O for file access."),
-			NULL,
+			gettext_noop("An empty string disables direct I/O."),
 			GUC_LIST_INPUT | GUC_NOT_IN_SAMPLE
 		},
 		&debug_io_direct_string,
-- 
2.39.5 (Apple Git-154)

From f2a6b6078f8d788df4818f10ad5b54667bef5dd2 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Fri, 7 Feb 2025 16:06:18 -0600
Subject: [PATCH v3 1/1] Describe special values in GUC descriptions more
 consistently.

---
 src/backend/utils/misc/guc_tables.c | 141 ++++++++++++++--------------
 1 file changed, 71 insertions(+), 70 deletions(-)

diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index ce7534d4d23..1dc5ccd5264 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -2109,7 +2109,7 @@ struct config_int ConfigureNamesInt[] =
 		{"archive_timeout", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the amount of time to wait before forcing a "
 						 "switch to the next WAL file."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_S
 		},
 		&XLogArchiveTimeout,
@@ -2186,7 +2186,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_pool_size", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of individuals in the population."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_pool_size,
@@ -2196,7 +2196,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_generations", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of iterations of the algorithm."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_generations,
@@ -2219,7 +2219,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_archive_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_archive_delay,
@@ -2230,7 +2230,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_streaming_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_streaming_delay,
@@ -2263,7 +2263,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_receiver_timeout", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum wait time to receive data from the sending server."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&wal_receiver_timeout,
@@ -2354,7 +2354,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"shared_memory_size_in_huge_pages", PGC_INTERNAL, PRESET_OPTIONS,
 			gettext_noop("Shows the number of huge pages needed for the main shared memory area."),
-			gettext_noop("-1 indicates that the value could not be determined."),
+			gettext_noop("-1 means huge pages are not supported."),
 			GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE | GUC_RUNTIME_COMPUTED
 		},
 		&shared_memory_size_in_huge_pages,
@@ -2376,7 +2376,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"commit_timestamp_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the commit timestamp cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&commit_timestamp_buffers,
@@ -2431,7 +2431,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"subtransaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the subtransaction cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&subtransaction_buffers,
@@ -2442,7 +2442,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the transaction status cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&transaction_buffers,
@@ -2626,7 +2626,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_vacuum_cost_limit", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost amount available before napping, for autovacuum."),
-			NULL
+			gettext_noop("-1 means use \"vacuum_cost_limit\".")
 		},
 		&autovacuum_vac_cost_limit,
 		-1, -1, 10000,
@@ -2682,7 +2682,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"statement_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any statement."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&StatementTimeout,
@@ -2693,7 +2693,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"lock_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any wait for a lock."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&LockTimeout,
@@ -2704,7 +2704,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_in_transaction_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleInTransactionSessionTimeout,
@@ -2715,7 +2715,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any transaction within a session (not a prepared transaction)."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&TransactionTimeout,
@@ -2726,7 +2726,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when not in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleSessionTimeout,
@@ -2940,7 +2940,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Write a message to the server log if checkpoints "
 						 "caused by the filling of WAL segment files happen more "
 						 "frequently than this amount of time. "
-						 "Zero turns off the warning."),
+						 "0 disables the warning."),
 			GUC_UNIT_S
 		},
 		&CheckPointWarning,
@@ -2951,7 +2951,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"checkpoint_flush_after", PGC_SIGHUP, WAL_CHECKPOINTS,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&checkpoint_flush_after,
@@ -2962,7 +2962,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_buffers", PGC_POSTMASTER, WAL_SETTINGS,
 			gettext_noop("Sets the number of disk-page buffers in shared memory for WAL."),
-			gettext_noop("Specify -1 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("-1 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_XBLOCKS
 		},
 		&XLOGbuffers,
@@ -3029,7 +3029,8 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the maximum WAL size that can be reserved by replication slots."),
 			gettext_noop("Replication slots will be marked as failed, and segments released "
 						 "for deletion or recycling, if this much space is occupied by WAL "
-						 "on disk."),
+						 "on disk. "
+						 "-1 means no maximum."),
 			GUC_UNIT_MB
 		},
 		&max_slot_wal_keep_size_mb,
@@ -3089,7 +3090,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the minimum execution time above which "
 						 "a sample of statements will be logged."
 						 " Sampling is determined by \"log_statement_sample_rate\"."),
-			gettext_noop("Zero logs a sample of all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables sampling. 0 means sample all statements."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_sample,
@@ -3101,7 +3102,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_min_duration_statement", PGC_SUSET, LOGGING_WHEN,
 			gettext_noop("Sets the minimum execution time above which "
 						 "all statements will be logged."),
-			gettext_noop("Zero prints all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables logging statement durations. 0 means log all statement durations."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_statement,
@@ -3113,7 +3114,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_autovacuum_min_duration", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Sets the minimum execution time above which "
 						 "autovacuum actions will be logged."),
-			gettext_noop("Zero prints all actions. -1 turns autovacuum logging off."),
+			gettext_noop("-1 disables logging autovacuum actions. 0 means log all autovacuum actions."),
 			GUC_UNIT_MS
 		},
 		&Log_autovacuum_min_duration,
@@ -3125,7 +3126,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length,
@@ -3137,7 +3138,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length_on_error", PGC_USERSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements, on error."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length_on_error,
@@ -3159,7 +3160,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_lru_maxpages", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Background writer maximum number of LRU pages to flush per round."),
-			NULL
+			gettext_noop("0 disables background writing.")
 		},
 		&bgwriter_lru_maxpages,
 		100, 0, INT_MAX / 2,	/* Same upper limit as shared_buffers */
@@ -3169,7 +3170,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_flush_after", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&bgwriter_flush_after,
@@ -3182,7 +3183,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_ASYNCHRONOUS,
 			gettext_noop("Number of simultaneous requests that can be handled efficiently by the disk subsystem."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&effective_io_concurrency,
@@ -3196,7 +3197,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_ASYNCHRONOUS,
 			gettext_noop("A variant of \"effective_io_concurrency\" that is used for maintenance work."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&maintenance_io_concurrency,
@@ -3223,7 +3224,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"backend_flush_after", PGC_USERSET, RESOURCES_ASYNCHRONOUS,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&backend_flush_after,
@@ -3283,7 +3284,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_age", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the amount of time to wait before forcing "
 						 "log file rotation."),
-			NULL,
+			gettext_noop("0 disables time-based creation of new log files."),
 			GUC_UNIT_MIN
 		},
 		&Log_RotationAge,
@@ -3295,7 +3296,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_size", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the maximum size a log file can reach before "
 						 "being rotated."),
-			NULL,
+			gettext_noop("0 disables size-based creation of new log files."),
 			GUC_UNIT_KB
 		},
 		&Log_RotationSize,
@@ -3397,7 +3398,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_summary_keep_time", PGC_SIGHUP, WAL_SUMMARIZATION,
 			gettext_noop("Time for which WAL summary files should be kept."),
-			NULL,
+			gettext_noop("0 disables automatic summary file deletion."),
 			GUC_UNIT_MIN,
 		},
 		&wal_summary_keep_time,
@@ -3428,8 +3429,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_max_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum, or -1 to disable maximum threshold."),
-			NULL
+			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum."),
+			gettext_noop("-1 disables the maximum threshold.")
 		},
 		&autovacuum_vac_max_thresh,
 		100000000, -1, INT_MAX,
@@ -3437,8 +3438,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_insert_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Minimum number of tuple inserts prior to vacuum, or -1 to disable insert vacuums."),
-			NULL
+			gettext_noop("Minimum number of tuple inserts prior to vacuum."),
+			gettext_noop("-1 disables insert vacuums.")
 		},
 		&autovacuum_vac_ins_thresh,
 		1000, -1, INT_MAX,
@@ -3530,7 +3531,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_work_mem", PGC_SIGHUP, RESOURCES_MEM,
 			gettext_noop("Sets the maximum memory to be used by each autovacuum worker process."),
-			NULL,
+			gettext_noop("-1 means use \"maintenance_work_mem\"."),
 			GUC_UNIT_KB
 		},
 		&autovacuum_work_mem,
@@ -3541,7 +3542,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_idle", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between issuing TCP keepalives."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_idle,
@@ -3552,7 +3553,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between TCP keepalive retransmits."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_interval,
@@ -3575,8 +3576,8 @@ struct config_int ConfigureNamesInt[] =
 		{"tcp_keepalives_count", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Maximum number of TCP keepalive retransmits."),
 			gettext_noop("Number of consecutive keepalive retransmits that can be "
-						 "lost before a connection is considered dead. A value of 0 uses the "
-						 "system default."),
+						 "lost before a connection is considered dead. "
+						 "0 means use the system default."),
 		},
 		&tcp_keepalives_count,
 		0, 0, INT_MAX,
@@ -3586,8 +3587,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"gin_fuzzy_search_limit", PGC_USERSET, CLIENT_CONN_OTHER,
 			gettext_noop("Sets the maximum allowed result for exact search by GIN."),
-			NULL,
-			0
+			gettext_noop("0 means no limit."),
 		},
 		&GinFuzzySearchLimit,
 		0, 0, INT_MAX,
@@ -3643,7 +3643,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"log_temp_files", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Log the use of temporary files larger than this number of kilobytes."),
-			gettext_noop("Zero logs all files. The default is -1 (turning this feature off)."),
+			gettext_noop("-1 disables temporary file logs. 0 means log all files."),
 			GUC_UNIT_KB
 		},
 		&log_temp_files,
@@ -3676,7 +3676,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_user_timeout", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("TCP user timeout."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_MS
 		},
 		&tcp_user_timeout,
@@ -3687,7 +3687,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"huge_page_size", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("The size of huge page that should be requested."),
-			NULL,
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_KB
 		},
 		&huge_page_size,
@@ -3698,7 +3698,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"debug_discard_caches", PGC_SUSET, DEVELOPER_OPTIONS,
 			gettext_noop("Aggressively flush system caches for debugging purposes."),
-			NULL,
+			gettext_noop("0 means use normal caching behavior."),
 			GUC_NOT_IN_SAMPLE
 		},
 		&debug_discard_caches,
@@ -3721,7 +3721,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"client_connection_check_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Sets the time interval between checks for disconnection while running queries."),
-			NULL,
+			gettext_noop("0 disables connection checks."),
 			GUC_UNIT_MS
 		},
 		&client_connection_check_interval,
@@ -3733,7 +3733,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_startup_progress_interval", PGC_SIGHUP, LOGGING_WHEN,
 			gettext_noop("Time between progress updates for "
 						 "long-running startup operations."),
-			gettext_noop("0 turns this feature off."),
+			gettext_noop("0 disables progress updates."),
 			GUC_UNIT_MS,
 		},
 		&log_startup_progress_interval,
@@ -3964,7 +3964,7 @@ struct config_real ConfigureNamesReal[] =
 	{
 		{"autovacuum_vacuum_cost_delay", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost delay in milliseconds, for autovacuum."),
-			NULL,
+			gettext_noop("-1 means use \"vacuum_cost_delay\"."),
 			GUC_UNIT_MS
 		},
 		&autovacuum_vac_cost_delay,
@@ -4045,7 +4045,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_command", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the shell command that will be called to archive a WAL file."),
-			gettext_noop("This is used only if \"archive_library\" is not set.")
+			gettext_noop("An empty string means use \"archive_library\".")
 		},
 		&XLogArchiveCommand,
 		"",
@@ -4055,7 +4055,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_library", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the library that will be called to archive a WAL file."),
-			gettext_noop("An empty string indicates that \"archive_command\" should be used.")
+			gettext_noop("An empty string means use \"archive_command\".")
 		},
 		&XLogArchiveLibrary,
 		"",
@@ -4183,7 +4183,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"log_line_prefix", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Controls information prefixed to each log line."),
-			gettext_noop("If blank, no prefix is used.")
+			gettext_noop("An empty string means no prefix.")
 		},
 		&Log_line_prefix,
 		"%m [%p] ",
@@ -4226,7 +4226,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"default_tablespace", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the default tablespace to create tables and indexes in."),
-			gettext_noop("An empty string selects the database's default tablespace."),
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_IS_NAME
 		},
 		&default_tablespace,
@@ -4237,7 +4237,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"temp_tablespaces", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the tablespace(s) to use for temporary tables and sort files."),
-			NULL,
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_LIST_INPUT | GUC_LIST_QUOTE
 		},
 		&temp_tablespaces,
@@ -4249,7 +4249,7 @@ struct config_string ConfigureNamesString[] =
 		{"createrole_self_grant", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets whether a CREATEROLE user automatically grants "
 						 "the role to themselves, and with which options."),
-			NULL,
+			gettext_noop("An empty string disables automatic self grants."),
 			GUC_LIST_INPUT
 		},
 		&createrole_self_grant,
@@ -4285,7 +4285,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"bonjour_name", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the Bonjour service name."),
-			NULL
+			gettext_noop("An empty string means use the computer name.")
 		},
 		&bonjour_name,
 		"",
@@ -4295,7 +4295,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_messages", PGC_SUSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the language in which messages are displayed."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_messages,
 		"",
@@ -4305,7 +4305,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_monetary", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting monetary amounts."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_monetary,
 		"C",
@@ -4315,7 +4315,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_numeric", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting numbers."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_numeric,
 		"C",
@@ -4325,7 +4325,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_time", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting date and time values."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_time,
 		"C",
@@ -4504,7 +4504,8 @@ struct config_string ConfigureNamesString[] =
 		{"unix_socket_group", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the owning group of the Unix-domain socket."),
 			gettext_noop("The owning user of the socket is always the user "
-						 "that starts the server.")
+						 "that starts the server. "
+						 "An empty string means use the user's default group.")
 		},
 		&Unix_socket_group,
 		"",
@@ -4630,7 +4631,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_ca_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL certificate authority file."),
-			NULL
+			gettext_noop("An empty string disables client certificate validation.")
 		},
 		&ssl_ca_file,
 		"",
@@ -4640,7 +4641,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_crl_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL certificate revocation list file."),
-			NULL
+			gettext_noop("An empty string means use \"ssl_crl_dir\".")
 		},
 		&ssl_crl_file,
 		"",
@@ -4650,7 +4651,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_crl_dir", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL certificate revocation list directory."),
-			NULL
+			gettext_noop("An empty string means use \"ssl_crl_file\".")
 		},
 		&ssl_crl_dir,
 		"",
@@ -4681,7 +4682,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_tls13_ciphers", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites (leave blank for default)."),
-			NULL,
+			gettext_noop("An empty string means use the default cipher suites."),
 			GUC_SUPERUSER_ONLY
 		},
 		&SSLCipherSuites,
@@ -4722,7 +4723,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_dh_params_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL DH parameters file."),
-			NULL,
+			gettext_noop("An empty string means use compiled-in default parameters."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_dh_params_file,
@@ -4733,7 +4734,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_passphrase_command", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Command to obtain passphrases for SSL."),
-			NULL,
+			gettext_noop("An empty string means use the built-in prompting mechanism."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_passphrase_command,
@@ -4799,7 +4800,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"debug_io_direct", PGC_POSTMASTER, DEVELOPER_OPTIONS,
 			gettext_noop("Use direct I/O for file access."),
-			NULL,
+			gettext_noop("An empty string disables direct I/O."),
 			GUC_LIST_INPUT | GUC_NOT_IN_SAMPLE
 		},
 		&debug_io_direct_string,
-- 
2.39.5 (Apple Git-154)

From 3205f1172ac6ec2a82171bba554bca17bb8702cb Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Wed, 12 Feb 2025 14:26:00 -0600
Subject: [PATCH v4 1/1] Describe special values in GUC descriptions more
 consistently.

Many GUCs accept special values like -1 or an empty string to
disable the feature, use a system default, etc.  While the
documentation consistently lists these special values, the GUC
descriptions do not.  Many such descriptions fail to mention the
special values, and those that do vary in phrasing and placement.
This commit aims to bring some consistency to this area by applying
the following rules:

* Special values should be listed at the end of the long
  description.
* Descriptions should use numerals (e.g., "0") instead of words
  (e.g., "zero").
* Special value mentions should be concise and direct (e.g., "0
  disables the timeout.", "An empty string means use the operating
  system setting.").
* Multiple special values should be listed in ascending order.

Of course, there are exceptions, such as
max_pred_locks_per_relation and search_path, whose special values
are too complex to include.  And there are cases like
listen_addresses, where the meaning of an empty string is arguably
too obvious to include.  In those cases, I've refrained from adding
special value information to the GUC description.

Reviewed-by: Peter Smith <smithpb2250@gmail.com>
Reviewed-by: "David G. Johnston" <david.g.johnston@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Discussion: https://postgr.es/m/Z6aIy4aywxUZHAo6%40nathan
---
 src/backend/utils/misc/guc_tables.c | 137 ++++++++++++++--------------
 1 file changed, 69 insertions(+), 68 deletions(-)

diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index 226af43fe23..de6d15386c4 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -2119,7 +2119,7 @@ struct config_int ConfigureNamesInt[] =
 		{"archive_timeout", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the amount of time to wait before forcing a "
 						 "switch to the next WAL file."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_S
 		},
 		&XLogArchiveTimeout,
@@ -2196,7 +2196,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_pool_size", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of individuals in the population."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_pool_size,
@@ -2206,7 +2206,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_generations", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of iterations of the algorithm."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_generations,
@@ -2229,7 +2229,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_archive_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_archive_delay,
@@ -2240,7 +2240,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_streaming_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_streaming_delay,
@@ -2273,7 +2273,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_receiver_timeout", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum wait time to receive data from the sending server."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&wal_receiver_timeout,
@@ -2364,7 +2364,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"shared_memory_size_in_huge_pages", PGC_INTERNAL, PRESET_OPTIONS,
 			gettext_noop("Shows the number of huge pages needed for the main shared memory area."),
-			gettext_noop("-1 indicates that the value could not be determined."),
+			gettext_noop("-1 means huge pages are not supported."),
 			GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE | GUC_RUNTIME_COMPUTED
 		},
 		&shared_memory_size_in_huge_pages,
@@ -2386,7 +2386,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"commit_timestamp_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the commit timestamp cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&commit_timestamp_buffers,
@@ -2441,7 +2441,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"subtransaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the subtransaction cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&subtransaction_buffers,
@@ -2452,7 +2452,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the transaction status cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&transaction_buffers,
@@ -2636,7 +2636,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_vacuum_cost_limit", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost amount available before napping, for autovacuum."),
-			NULL
+			gettext_noop("-1 means use \"vacuum_cost_limit\".")
 		},
 		&autovacuum_vac_cost_limit,
 		-1, -1, 10000,
@@ -2692,7 +2692,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"statement_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any statement."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&StatementTimeout,
@@ -2703,7 +2703,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"lock_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any wait for a lock."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&LockTimeout,
@@ -2714,7 +2714,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_in_transaction_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleInTransactionSessionTimeout,
@@ -2725,7 +2725,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any transaction within a session (not a prepared transaction)."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&TransactionTimeout,
@@ -2736,7 +2736,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when not in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleSessionTimeout,
@@ -2950,7 +2950,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Write a message to the server log if checkpoints "
 						 "caused by the filling of WAL segment files happen more "
 						 "frequently than this amount of time. "
-						 "Zero turns off the warning."),
+						 "0 disables the warning."),
 			GUC_UNIT_S
 		},
 		&CheckPointWarning,
@@ -2961,7 +2961,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"checkpoint_flush_after", PGC_SIGHUP, WAL_CHECKPOINTS,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&checkpoint_flush_after,
@@ -2972,7 +2972,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_buffers", PGC_POSTMASTER, WAL_SETTINGS,
 			gettext_noop("Sets the number of disk-page buffers in shared memory for WAL."),
-			gettext_noop("Specify -1 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("-1 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_XBLOCKS
 		},
 		&XLOGbuffers,
@@ -3039,7 +3039,8 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the maximum WAL size that can be reserved by replication slots."),
 			gettext_noop("Replication slots will be marked as failed, and segments released "
 						 "for deletion or recycling, if this much space is occupied by WAL "
-						 "on disk."),
+						 "on disk. "
+						 "-1 means no maximum."),
 			GUC_UNIT_MB
 		},
 		&max_slot_wal_keep_size_mb,
@@ -3099,7 +3100,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the minimum execution time above which "
 						 "a sample of statements will be logged."
 						 " Sampling is determined by \"log_statement_sample_rate\"."),
-			gettext_noop("Zero logs a sample of all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables sampling. 0 means sample all statements."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_sample,
@@ -3111,7 +3112,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_min_duration_statement", PGC_SUSET, LOGGING_WHEN,
 			gettext_noop("Sets the minimum execution time above which "
 						 "all statements will be logged."),
-			gettext_noop("Zero prints all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables logging statement durations. 0 means log all statement durations."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_statement,
@@ -3123,7 +3124,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_autovacuum_min_duration", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Sets the minimum execution time above which "
 						 "autovacuum actions will be logged."),
-			gettext_noop("Zero prints all actions. -1 turns autovacuum logging off."),
+			gettext_noop("-1 disables logging autovacuum actions. 0 means log all autovacuum actions."),
 			GUC_UNIT_MS
 		},
 		&Log_autovacuum_min_duration,
@@ -3135,7 +3136,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length,
@@ -3147,7 +3148,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length_on_error", PGC_USERSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements, on error."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length_on_error,
@@ -3169,7 +3170,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_lru_maxpages", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Background writer maximum number of LRU pages to flush per round."),
-			NULL
+			gettext_noop("0 disables background writing.")
 		},
 		&bgwriter_lru_maxpages,
 		100, 0, INT_MAX / 2,	/* Same upper limit as shared_buffers */
@@ -3179,7 +3180,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_flush_after", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&bgwriter_flush_after,
@@ -3192,7 +3193,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_IO,
 			gettext_noop("Number of simultaneous requests that can be handled efficiently by the disk subsystem."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&effective_io_concurrency,
@@ -3206,7 +3207,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_IO,
 			gettext_noop("A variant of \"effective_io_concurrency\" that is used for maintenance work."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&maintenance_io_concurrency,
@@ -3233,7 +3234,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"backend_flush_after", PGC_USERSET, RESOURCES_IO,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&backend_flush_after,
@@ -3293,7 +3294,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_age", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the amount of time to wait before forcing "
 						 "log file rotation."),
-			NULL,
+			gettext_noop("0 disables time-based creation of new log files."),
 			GUC_UNIT_MIN
 		},
 		&Log_RotationAge,
@@ -3305,7 +3306,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_size", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the maximum size a log file can reach before "
 						 "being rotated."),
-			NULL,
+			gettext_noop("0 disables size-based creation of new log files."),
 			GUC_UNIT_KB
 		},
 		&Log_RotationSize,
@@ -3407,7 +3408,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_summary_keep_time", PGC_SIGHUP, WAL_SUMMARIZATION,
 			gettext_noop("Time for which WAL summary files should be kept."),
-			NULL,
+			gettext_noop("0 disables automatic summary file deletion."),
 			GUC_UNIT_MIN,
 		},
 		&wal_summary_keep_time,
@@ -3438,8 +3439,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_max_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum, or -1 to disable maximum threshold."),
-			NULL
+			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum."),
+			gettext_noop("-1 disables the maximum threshold.")
 		},
 		&autovacuum_vac_max_thresh,
 		100000000, -1, INT_MAX,
@@ -3447,8 +3448,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_insert_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Minimum number of tuple inserts prior to vacuum, or -1 to disable insert vacuums."),
-			NULL
+			gettext_noop("Minimum number of tuple inserts prior to vacuum."),
+			gettext_noop("-1 disables insert vacuums.")
 		},
 		&autovacuum_vac_ins_thresh,
 		1000, -1, INT_MAX,
@@ -3540,7 +3541,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_work_mem", PGC_SIGHUP, RESOURCES_MEM,
 			gettext_noop("Sets the maximum memory to be used by each autovacuum worker process."),
-			NULL,
+			gettext_noop("-1 means use \"maintenance_work_mem\"."),
 			GUC_UNIT_KB
 		},
 		&autovacuum_work_mem,
@@ -3551,7 +3552,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_idle", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between issuing TCP keepalives."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_idle,
@@ -3562,7 +3563,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between TCP keepalive retransmits."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_interval,
@@ -3585,8 +3586,8 @@ struct config_int ConfigureNamesInt[] =
 		{"tcp_keepalives_count", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Maximum number of TCP keepalive retransmits."),
 			gettext_noop("Number of consecutive keepalive retransmits that can be "
-						 "lost before a connection is considered dead. A value of 0 uses the "
-						 "system default."),
+						 "lost before a connection is considered dead. "
+						 "0 means use the system default."),
 		},
 		&tcp_keepalives_count,
 		0, 0, INT_MAX,
@@ -3596,8 +3597,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"gin_fuzzy_search_limit", PGC_USERSET, CLIENT_CONN_OTHER,
 			gettext_noop("Sets the maximum allowed result for exact search by GIN."),
-			NULL,
-			0
+			gettext_noop("0 means no limit."),
 		},
 		&GinFuzzySearchLimit,
 		0, 0, INT_MAX,
@@ -3653,7 +3653,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"log_temp_files", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Log the use of temporary files larger than this number of kilobytes."),
-			gettext_noop("Zero logs all files. The default is -1 (turning this feature off)."),
+			gettext_noop("-1 disables temporary file logs. 0 means log all temporary files."),
 			GUC_UNIT_KB
 		},
 		&log_temp_files,
@@ -3686,7 +3686,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_user_timeout", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("TCP user timeout."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_MS
 		},
 		&tcp_user_timeout,
@@ -3697,7 +3697,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"huge_page_size", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("The size of huge page that should be requested."),
-			NULL,
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_KB
 		},
 		&huge_page_size,
@@ -3708,7 +3708,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"debug_discard_caches", PGC_SUSET, DEVELOPER_OPTIONS,
 			gettext_noop("Aggressively flush system caches for debugging purposes."),
-			NULL,
+			gettext_noop("0 means use normal caching behavior."),
 			GUC_NOT_IN_SAMPLE
 		},
 		&debug_discard_caches,
@@ -3731,7 +3731,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"client_connection_check_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Sets the time interval between checks for disconnection while running queries."),
-			NULL,
+			gettext_noop("0 disables connection checks."),
 			GUC_UNIT_MS
 		},
 		&client_connection_check_interval,
@@ -3743,7 +3743,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_startup_progress_interval", PGC_SIGHUP, LOGGING_WHEN,
 			gettext_noop("Time between progress updates for "
 						 "long-running startup operations."),
-			gettext_noop("0 turns this feature off."),
+			gettext_noop("0 disables progress updates."),
 			GUC_UNIT_MS,
 		},
 		&log_startup_progress_interval,
@@ -3974,7 +3974,7 @@ struct config_real ConfigureNamesReal[] =
 	{
 		{"autovacuum_vacuum_cost_delay", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost delay in milliseconds, for autovacuum."),
-			NULL,
+			gettext_noop("-1 means use \"vacuum_cost_delay\"."),
 			GUC_UNIT_MS
 		},
 		&autovacuum_vac_cost_delay,
@@ -4065,7 +4065,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_command", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the shell command that will be called to archive a WAL file."),
-			gettext_noop("This is used only if \"archive_library\" is not set.")
+			gettext_noop("An empty string means use \"archive_library\".")
 		},
 		&XLogArchiveCommand,
 		"",
@@ -4075,7 +4075,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_library", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the library that will be called to archive a WAL file."),
-			gettext_noop("An empty string indicates that \"archive_command\" should be used.")
+			gettext_noop("An empty string means use \"archive_command\".")
 		},
 		&XLogArchiveLibrary,
 		"",
@@ -4203,7 +4203,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"log_line_prefix", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Controls information prefixed to each log line."),
-			gettext_noop("If blank, no prefix is used.")
+			gettext_noop("An empty string means no prefix.")
 		},
 		&Log_line_prefix,
 		"%m [%p] ",
@@ -4246,7 +4246,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"default_tablespace", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the default tablespace to create tables and indexes in."),
-			gettext_noop("An empty string selects the database's default tablespace."),
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_IS_NAME
 		},
 		&default_tablespace,
@@ -4257,7 +4257,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"temp_tablespaces", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the tablespace(s) to use for temporary tables and sort files."),
-			NULL,
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_LIST_INPUT | GUC_LIST_QUOTE
 		},
 		&temp_tablespaces,
@@ -4269,7 +4269,7 @@ struct config_string ConfigureNamesString[] =
 		{"createrole_self_grant", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets whether a CREATEROLE user automatically grants "
 						 "the role to themselves, and with which options."),
-			NULL,
+			gettext_noop("An empty string disables automatic self grants."),
 			GUC_LIST_INPUT
 		},
 		&createrole_self_grant,
@@ -4305,7 +4305,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"bonjour_name", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the Bonjour service name."),
-			NULL
+			gettext_noop("An empty string means use the computer name.")
 		},
 		&bonjour_name,
 		"",
@@ -4315,7 +4315,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_messages", PGC_SUSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the language in which messages are displayed."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_messages,
 		"",
@@ -4325,7 +4325,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_monetary", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting monetary amounts."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_monetary,
 		"C",
@@ -4335,7 +4335,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_numeric", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting numbers."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_numeric,
 		"C",
@@ -4345,7 +4345,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_time", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting date and time values."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_time,
 		"C",
@@ -4524,7 +4524,8 @@ struct config_string ConfigureNamesString[] =
 		{"unix_socket_group", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the owning group of the Unix-domain socket."),
 			gettext_noop("The owning user of the socket is always the user "
-						 "that starts the server.")
+						 "that starts the server. "
+						 "An empty string means use the user's default group.")
 		},
 		&Unix_socket_group,
 		"",
@@ -4700,8 +4701,8 @@ struct config_string ConfigureNamesString[] =
 
 	{
 		{"ssl_tls13_ciphers", PGC_SIGHUP, CONN_AUTH_SSL,
-			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites (leave blank for default)."),
-			NULL,
+			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites."),
+			gettext_noop("An empty string means use the default cipher suites."),
 			GUC_SUPERUSER_ONLY
 		},
 		&SSLCipherSuites,
@@ -4742,7 +4743,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_dh_params_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL DH parameters file."),
-			NULL,
+			gettext_noop("An empty string means use compiled-in default parameters."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_dh_params_file,
@@ -4753,7 +4754,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_passphrase_command", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Command to obtain passphrases for SSL."),
-			NULL,
+			gettext_noop("An empty string means use the built-in prompting mechanism."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_passphrase_command,
@@ -4819,7 +4820,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"debug_io_direct", PGC_POSTMASTER, DEVELOPER_OPTIONS,
 			gettext_noop("Use direct I/O for file access."),
-			NULL,
+			gettext_noop("An empty string disables direct I/O."),
 			GUC_LIST_INPUT | GUC_NOT_IN_SAMPLE
 		},
 		&debug_io_direct_string,
-- 
2.39.5 (Apple Git-154)

From f5e757046c40bfa118c10cae82edc55dc7679dca Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Wed, 12 Feb 2025 14:26:00 -0600
Subject: [PATCH v5 1/1] Describe special values in GUC descriptions more
 consistently.

Many GUCs accept special values like -1 or an empty string to
disable the feature, use a system default, etc.  While the
documentation consistently lists these special values, the GUC
descriptions do not.  Many such descriptions fail to mention the
special values, and those that do vary in phrasing and placement.
This commit aims to bring some consistency to this area by applying
the following rules:

* Special values should be listed at the end of the long
  description.
* Descriptions should use numerals (e.g., "0") instead of words
  (e.g., "zero").
* Special value mentions should be concise and direct (e.g., "0
  disables the timeout.", "An empty string means use the operating
  system setting.").
* Multiple special values should be listed in ascending order.

Of course, there are exceptions, such as
max_pred_locks_per_relation and search_path, whose special values
are too complex to include.  And there are cases like
listen_addresses, where the meaning of an empty string is arguably
too obvious to include.  In those cases, I've refrained from adding
special value information to the GUC description.

Reviewed-by: Peter Smith <smithpb2250@gmail.com>
Reviewed-by: "David G. Johnston" <david.g.johnston@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Discussion: https://postgr.es/m/Z6aIy4aywxUZHAo6%40nathan
---
 src/backend/utils/misc/guc_tables.c | 138 ++++++++++++++--------------
 1 file changed, 69 insertions(+), 69 deletions(-)

diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index 226af43fe23..408bd5969b8 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -2119,7 +2119,7 @@ struct config_int ConfigureNamesInt[] =
 		{"archive_timeout", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the amount of time to wait before forcing a "
 						 "switch to the next WAL file."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_S
 		},
 		&XLogArchiveTimeout,
@@ -2196,7 +2196,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_pool_size", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of individuals in the population."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_pool_size,
@@ -2206,7 +2206,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_generations", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of iterations of the algorithm."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_generations,
@@ -2229,7 +2229,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_archive_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_archive_delay,
@@ -2240,7 +2240,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_streaming_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_streaming_delay,
@@ -2273,7 +2273,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_receiver_timeout", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum wait time to receive data from the sending server."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&wal_receiver_timeout,
@@ -2364,7 +2364,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"shared_memory_size_in_huge_pages", PGC_INTERNAL, PRESET_OPTIONS,
 			gettext_noop("Shows the number of huge pages needed for the main shared memory area."),
-			gettext_noop("-1 indicates that the value could not be determined."),
+			gettext_noop("-1 means huge pages are not supported."),
 			GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE | GUC_RUNTIME_COMPUTED
 		},
 		&shared_memory_size_in_huge_pages,
@@ -2386,7 +2386,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"commit_timestamp_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the commit timestamp cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&commit_timestamp_buffers,
@@ -2441,7 +2441,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"subtransaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the subtransaction cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&subtransaction_buffers,
@@ -2452,7 +2452,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the transaction status cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&transaction_buffers,
@@ -2636,7 +2636,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_vacuum_cost_limit", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost amount available before napping, for autovacuum."),
-			NULL
+			gettext_noop("-1 means use \"vacuum_cost_limit\".")
 		},
 		&autovacuum_vac_cost_limit,
 		-1, -1, 10000,
@@ -2692,7 +2692,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"statement_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any statement."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&StatementTimeout,
@@ -2703,7 +2703,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"lock_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any wait for a lock."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&LockTimeout,
@@ -2714,7 +2714,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_in_transaction_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleInTransactionSessionTimeout,
@@ -2725,7 +2725,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any transaction within a session (not a prepared transaction)."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&TransactionTimeout,
@@ -2736,7 +2736,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when not in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleSessionTimeout,
@@ -2949,8 +2949,8 @@ struct config_int ConfigureNamesInt[] =
 						 "triggered by WAL volume happen too frequently."),
 			gettext_noop("Write a message to the server log if checkpoints "
 						 "caused by the filling of WAL segment files happen more "
-						 "frequently than this amount of time. "
-						 "Zero turns off the warning."),
+						 "frequently than this amount of time. 0 disables the "
+						 "warning."),
 			GUC_UNIT_S
 		},
 		&CheckPointWarning,
@@ -2961,7 +2961,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"checkpoint_flush_after", PGC_SIGHUP, WAL_CHECKPOINTS,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&checkpoint_flush_after,
@@ -2972,7 +2972,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_buffers", PGC_POSTMASTER, WAL_SETTINGS,
 			gettext_noop("Sets the number of disk-page buffers in shared memory for WAL."),
-			gettext_noop("Specify -1 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("-1 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_XBLOCKS
 		},
 		&XLOGbuffers,
@@ -3039,7 +3039,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the maximum WAL size that can be reserved by replication slots."),
 			gettext_noop("Replication slots will be marked as failed, and segments released "
 						 "for deletion or recycling, if this much space is occupied by WAL "
-						 "on disk."),
+						 "on disk. -1 means no maximum."),
 			GUC_UNIT_MB
 		},
 		&max_slot_wal_keep_size_mb,
@@ -3099,7 +3099,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the minimum execution time above which "
 						 "a sample of statements will be logged."
 						 " Sampling is determined by \"log_statement_sample_rate\"."),
-			gettext_noop("Zero logs a sample of all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables sampling. 0 means sample all statements."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_sample,
@@ -3111,7 +3111,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_min_duration_statement", PGC_SUSET, LOGGING_WHEN,
 			gettext_noop("Sets the minimum execution time above which "
 						 "all statements will be logged."),
-			gettext_noop("Zero prints all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables logging statement durations. 0 means log all statement durations."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_statement,
@@ -3123,7 +3123,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_autovacuum_min_duration", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Sets the minimum execution time above which "
 						 "autovacuum actions will be logged."),
-			gettext_noop("Zero prints all actions. -1 turns autovacuum logging off."),
+			gettext_noop("-1 disables logging autovacuum actions. 0 means log all autovacuum actions."),
 			GUC_UNIT_MS
 		},
 		&Log_autovacuum_min_duration,
@@ -3135,7 +3135,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length,
@@ -3147,7 +3147,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length_on_error", PGC_USERSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements, on error."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length_on_error,
@@ -3169,7 +3169,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_lru_maxpages", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Background writer maximum number of LRU pages to flush per round."),
-			NULL
+			gettext_noop("0 disables background writing.")
 		},
 		&bgwriter_lru_maxpages,
 		100, 0, INT_MAX / 2,	/* Same upper limit as shared_buffers */
@@ -3179,7 +3179,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_flush_after", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&bgwriter_flush_after,
@@ -3192,7 +3192,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_IO,
 			gettext_noop("Number of simultaneous requests that can be handled efficiently by the disk subsystem."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&effective_io_concurrency,
@@ -3206,7 +3206,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_IO,
 			gettext_noop("A variant of \"effective_io_concurrency\" that is used for maintenance work."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&maintenance_io_concurrency,
@@ -3233,7 +3233,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"backend_flush_after", PGC_USERSET, RESOURCES_IO,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&backend_flush_after,
@@ -3293,7 +3293,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_age", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the amount of time to wait before forcing "
 						 "log file rotation."),
-			NULL,
+			gettext_noop("0 disables time-based creation of new log files."),
 			GUC_UNIT_MIN
 		},
 		&Log_RotationAge,
@@ -3305,7 +3305,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_size", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the maximum size a log file can reach before "
 						 "being rotated."),
-			NULL,
+			gettext_noop("0 disables size-based creation of new log files."),
 			GUC_UNIT_KB
 		},
 		&Log_RotationSize,
@@ -3407,7 +3407,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_summary_keep_time", PGC_SIGHUP, WAL_SUMMARIZATION,
 			gettext_noop("Time for which WAL summary files should be kept."),
-			NULL,
+			gettext_noop("0 disables automatic summary file deletion."),
 			GUC_UNIT_MIN,
 		},
 		&wal_summary_keep_time,
@@ -3438,8 +3438,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_max_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum, or -1 to disable maximum threshold."),
-			NULL
+			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum."),
+			gettext_noop("-1 disables the maximum threshold.")
 		},
 		&autovacuum_vac_max_thresh,
 		100000000, -1, INT_MAX,
@@ -3447,8 +3447,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_insert_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Minimum number of tuple inserts prior to vacuum, or -1 to disable insert vacuums."),
-			NULL
+			gettext_noop("Minimum number of tuple inserts prior to vacuum."),
+			gettext_noop("-1 disables insert vacuums.")
 		},
 		&autovacuum_vac_ins_thresh,
 		1000, -1, INT_MAX,
@@ -3540,7 +3540,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_work_mem", PGC_SIGHUP, RESOURCES_MEM,
 			gettext_noop("Sets the maximum memory to be used by each autovacuum worker process."),
-			NULL,
+			gettext_noop("-1 means use \"maintenance_work_mem\"."),
 			GUC_UNIT_KB
 		},
 		&autovacuum_work_mem,
@@ -3551,7 +3551,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_idle", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between issuing TCP keepalives."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_idle,
@@ -3562,7 +3562,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between TCP keepalive retransmits."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_interval,
@@ -3585,8 +3585,8 @@ struct config_int ConfigureNamesInt[] =
 		{"tcp_keepalives_count", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Maximum number of TCP keepalive retransmits."),
 			gettext_noop("Number of consecutive keepalive retransmits that can be "
-						 "lost before a connection is considered dead. A value of 0 uses the "
-						 "system default."),
+						 "lost before a connection is considered dead. 0 "
+						 "means use the system default."),
 		},
 		&tcp_keepalives_count,
 		0, 0, INT_MAX,
@@ -3596,8 +3596,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"gin_fuzzy_search_limit", PGC_USERSET, CLIENT_CONN_OTHER,
 			gettext_noop("Sets the maximum allowed result for exact search by GIN."),
-			NULL,
-			0
+			gettext_noop("0 means no limit."),
 		},
 		&GinFuzzySearchLimit,
 		0, 0, INT_MAX,
@@ -3653,7 +3652,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"log_temp_files", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Log the use of temporary files larger than this number of kilobytes."),
-			gettext_noop("Zero logs all files. The default is -1 (turning this feature off)."),
+			gettext_noop("-1 disables logging temporary files. 0 means log all temporary files."),
 			GUC_UNIT_KB
 		},
 		&log_temp_files,
@@ -3686,7 +3685,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_user_timeout", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("TCP user timeout."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_MS
 		},
 		&tcp_user_timeout,
@@ -3697,7 +3696,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"huge_page_size", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("The size of huge page that should be requested."),
-			NULL,
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_KB
 		},
 		&huge_page_size,
@@ -3708,7 +3707,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"debug_discard_caches", PGC_SUSET, DEVELOPER_OPTIONS,
 			gettext_noop("Aggressively flush system caches for debugging purposes."),
-			NULL,
+			gettext_noop("0 means use normal caching behavior."),
 			GUC_NOT_IN_SAMPLE
 		},
 		&debug_discard_caches,
@@ -3731,7 +3730,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"client_connection_check_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Sets the time interval between checks for disconnection while running queries."),
-			NULL,
+			gettext_noop("0 disables connection checks."),
 			GUC_UNIT_MS
 		},
 		&client_connection_check_interval,
@@ -3743,7 +3742,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_startup_progress_interval", PGC_SIGHUP, LOGGING_WHEN,
 			gettext_noop("Time between progress updates for "
 						 "long-running startup operations."),
-			gettext_noop("0 turns this feature off."),
+			gettext_noop("0 disables progress updates."),
 			GUC_UNIT_MS,
 		},
 		&log_startup_progress_interval,
@@ -3974,7 +3973,7 @@ struct config_real ConfigureNamesReal[] =
 	{
 		{"autovacuum_vacuum_cost_delay", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost delay in milliseconds, for autovacuum."),
-			NULL,
+			gettext_noop("-1 means use \"vacuum_cost_delay\"."),
 			GUC_UNIT_MS
 		},
 		&autovacuum_vac_cost_delay,
@@ -4065,7 +4064,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_command", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the shell command that will be called to archive a WAL file."),
-			gettext_noop("This is used only if \"archive_library\" is not set.")
+			gettext_noop("An empty string means use \"archive_library\".")
 		},
 		&XLogArchiveCommand,
 		"",
@@ -4075,7 +4074,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_library", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the library that will be called to archive a WAL file."),
-			gettext_noop("An empty string indicates that \"archive_command\" should be used.")
+			gettext_noop("An empty string means use \"archive_command\".")
 		},
 		&XLogArchiveLibrary,
 		"",
@@ -4203,7 +4202,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"log_line_prefix", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Controls information prefixed to each log line."),
-			gettext_noop("If blank, no prefix is used.")
+			gettext_noop("An empty string means no prefix.")
 		},
 		&Log_line_prefix,
 		"%m [%p] ",
@@ -4246,7 +4245,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"default_tablespace", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the default tablespace to create tables and indexes in."),
-			gettext_noop("An empty string selects the database's default tablespace."),
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_IS_NAME
 		},
 		&default_tablespace,
@@ -4257,7 +4256,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"temp_tablespaces", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the tablespace(s) to use for temporary tables and sort files."),
-			NULL,
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_LIST_INPUT | GUC_LIST_QUOTE
 		},
 		&temp_tablespaces,
@@ -4269,7 +4268,7 @@ struct config_string ConfigureNamesString[] =
 		{"createrole_self_grant", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets whether a CREATEROLE user automatically grants "
 						 "the role to themselves, and with which options."),
-			NULL,
+			gettext_noop("An empty string disables automatic self grants."),
 			GUC_LIST_INPUT
 		},
 		&createrole_self_grant,
@@ -4305,7 +4304,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"bonjour_name", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the Bonjour service name."),
-			NULL
+			gettext_noop("An empty string means use the computer name.")
 		},
 		&bonjour_name,
 		"",
@@ -4315,7 +4314,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_messages", PGC_SUSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the language in which messages are displayed."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_messages,
 		"",
@@ -4325,7 +4324,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_monetary", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting monetary amounts."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_monetary,
 		"C",
@@ -4335,7 +4334,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_numeric", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting numbers."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_numeric,
 		"C",
@@ -4345,7 +4344,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_time", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting date and time values."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_time,
 		"C",
@@ -4524,7 +4523,8 @@ struct config_string ConfigureNamesString[] =
 		{"unix_socket_group", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the owning group of the Unix-domain socket."),
 			gettext_noop("The owning user of the socket is always the user "
-						 "that starts the server.")
+						 "that starts the server. An empty string means use "
+						 "the user's default group.")
 		},
 		&Unix_socket_group,
 		"",
@@ -4700,8 +4700,8 @@ struct config_string ConfigureNamesString[] =
 
 	{
 		{"ssl_tls13_ciphers", PGC_SIGHUP, CONN_AUTH_SSL,
-			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites (leave blank for default)."),
-			NULL,
+			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites."),
+			gettext_noop("An empty string means use the default cipher suites."),
 			GUC_SUPERUSER_ONLY
 		},
 		&SSLCipherSuites,
@@ -4742,7 +4742,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_dh_params_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL DH parameters file."),
-			NULL,
+			gettext_noop("An empty string means use compiled-in default parameters."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_dh_params_file,
@@ -4753,7 +4753,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_passphrase_command", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Command to obtain passphrases for SSL."),
-			NULL,
+			gettext_noop("An empty string means use the built-in prompting mechanism."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_passphrase_command,
@@ -4819,7 +4819,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"debug_io_direct", PGC_POSTMASTER, DEVELOPER_OPTIONS,
 			gettext_noop("Use direct I/O for file access."),
-			NULL,
+			gettext_noop("An empty string disables direct I/O."),
 			GUC_LIST_INPUT | GUC_NOT_IN_SAMPLE
 		},
 		&debug_io_direct_string,
-- 
2.39.5 (Apple Git-154)

From 747384f1e0fe9f56cd6cf8363c74920b99028a4f Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Wed, 12 Feb 2025 14:26:00 -0600
Subject: [PATCH v6 1/1] Describe special values in GUC descriptions more
 consistently.

Many GUCs accept special values like -1 or an empty string to
disable the feature, use a system default, etc.  While the
documentation consistently lists these special values, the GUC
descriptions do not.  Many such descriptions fail to mention the
special values, and those that do vary in phrasing and placement.
This commit aims to bring some consistency to this area by applying
the following rules:

* Special values should be listed at the end of the long
  description.
* Descriptions should use numerals (e.g., "0") instead of words
  (e.g., "zero").
* Special value mentions should be concise and direct (e.g., "0
  disables the timeout.", "An empty string means use the operating
  system setting.").
* Multiple special values should be listed in ascending order.

Of course, there are exceptions, such as
max_pred_locks_per_relation and search_path, whose special values
are too complex to include.  And there are cases like
listen_addresses, where the meaning of an empty string is arguably
too obvious to include.  In those cases, I've refrained from adding
special value information to the GUC description.

Reviewed-by: Peter Smith <smithpb2250@gmail.com>
Reviewed-by: "David G. Johnston" <david.g.johnston@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Discussion: https://postgr.es/m/Z6aIy4aywxUZHAo6%40nathan
---
 src/backend/utils/misc/guc_tables.c | 138 ++++++++++++++--------------
 src/include/utils/guc_tables.h      |  15 +++
 2 files changed, 84 insertions(+), 69 deletions(-)

diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index 226af43fe23..408bd5969b8 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -2119,7 +2119,7 @@ struct config_int ConfigureNamesInt[] =
 		{"archive_timeout", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the amount of time to wait before forcing a "
 						 "switch to the next WAL file."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_S
 		},
 		&XLogArchiveTimeout,
@@ -2196,7 +2196,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_pool_size", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of individuals in the population."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_pool_size,
@@ -2206,7 +2206,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_generations", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of iterations of the algorithm."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_generations,
@@ -2229,7 +2229,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_archive_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_archive_delay,
@@ -2240,7 +2240,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_streaming_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_streaming_delay,
@@ -2273,7 +2273,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_receiver_timeout", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum wait time to receive data from the sending server."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&wal_receiver_timeout,
@@ -2364,7 +2364,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"shared_memory_size_in_huge_pages", PGC_INTERNAL, PRESET_OPTIONS,
 			gettext_noop("Shows the number of huge pages needed for the main shared memory area."),
-			gettext_noop("-1 indicates that the value could not be determined."),
+			gettext_noop("-1 means huge pages are not supported."),
 			GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE | GUC_RUNTIME_COMPUTED
 		},
 		&shared_memory_size_in_huge_pages,
@@ -2386,7 +2386,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"commit_timestamp_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the commit timestamp cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&commit_timestamp_buffers,
@@ -2441,7 +2441,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"subtransaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the subtransaction cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&subtransaction_buffers,
@@ -2452,7 +2452,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the transaction status cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&transaction_buffers,
@@ -2636,7 +2636,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_vacuum_cost_limit", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost amount available before napping, for autovacuum."),
-			NULL
+			gettext_noop("-1 means use \"vacuum_cost_limit\".")
 		},
 		&autovacuum_vac_cost_limit,
 		-1, -1, 10000,
@@ -2692,7 +2692,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"statement_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any statement."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&StatementTimeout,
@@ -2703,7 +2703,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"lock_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any wait for a lock."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&LockTimeout,
@@ -2714,7 +2714,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_in_transaction_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleInTransactionSessionTimeout,
@@ -2725,7 +2725,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any transaction within a session (not a prepared transaction)."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&TransactionTimeout,
@@ -2736,7 +2736,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when not in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleSessionTimeout,
@@ -2949,8 +2949,8 @@ struct config_int ConfigureNamesInt[] =
 						 "triggered by WAL volume happen too frequently."),
 			gettext_noop("Write a message to the server log if checkpoints "
 						 "caused by the filling of WAL segment files happen more "
-						 "frequently than this amount of time. "
-						 "Zero turns off the warning."),
+						 "frequently than this amount of time. 0 disables the "
+						 "warning."),
 			GUC_UNIT_S
 		},
 		&CheckPointWarning,
@@ -2961,7 +2961,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"checkpoint_flush_after", PGC_SIGHUP, WAL_CHECKPOINTS,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&checkpoint_flush_after,
@@ -2972,7 +2972,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_buffers", PGC_POSTMASTER, WAL_SETTINGS,
 			gettext_noop("Sets the number of disk-page buffers in shared memory for WAL."),
-			gettext_noop("Specify -1 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("-1 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_XBLOCKS
 		},
 		&XLOGbuffers,
@@ -3039,7 +3039,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the maximum WAL size that can be reserved by replication slots."),
 			gettext_noop("Replication slots will be marked as failed, and segments released "
 						 "for deletion or recycling, if this much space is occupied by WAL "
-						 "on disk."),
+						 "on disk. -1 means no maximum."),
 			GUC_UNIT_MB
 		},
 		&max_slot_wal_keep_size_mb,
@@ -3099,7 +3099,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the minimum execution time above which "
 						 "a sample of statements will be logged."
 						 " Sampling is determined by \"log_statement_sample_rate\"."),
-			gettext_noop("Zero logs a sample of all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables sampling. 0 means sample all statements."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_sample,
@@ -3111,7 +3111,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_min_duration_statement", PGC_SUSET, LOGGING_WHEN,
 			gettext_noop("Sets the minimum execution time above which "
 						 "all statements will be logged."),
-			gettext_noop("Zero prints all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables logging statement durations. 0 means log all statement durations."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_statement,
@@ -3123,7 +3123,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_autovacuum_min_duration", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Sets the minimum execution time above which "
 						 "autovacuum actions will be logged."),
-			gettext_noop("Zero prints all actions. -1 turns autovacuum logging off."),
+			gettext_noop("-1 disables logging autovacuum actions. 0 means log all autovacuum actions."),
 			GUC_UNIT_MS
 		},
 		&Log_autovacuum_min_duration,
@@ -3135,7 +3135,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length,
@@ -3147,7 +3147,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length_on_error", PGC_USERSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements, on error."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length_on_error,
@@ -3169,7 +3169,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_lru_maxpages", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Background writer maximum number of LRU pages to flush per round."),
-			NULL
+			gettext_noop("0 disables background writing.")
 		},
 		&bgwriter_lru_maxpages,
 		100, 0, INT_MAX / 2,	/* Same upper limit as shared_buffers */
@@ -3179,7 +3179,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_flush_after", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&bgwriter_flush_after,
@@ -3192,7 +3192,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_IO,
 			gettext_noop("Number of simultaneous requests that can be handled efficiently by the disk subsystem."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&effective_io_concurrency,
@@ -3206,7 +3206,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_IO,
 			gettext_noop("A variant of \"effective_io_concurrency\" that is used for maintenance work."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&maintenance_io_concurrency,
@@ -3233,7 +3233,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"backend_flush_after", PGC_USERSET, RESOURCES_IO,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&backend_flush_after,
@@ -3293,7 +3293,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_age", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the amount of time to wait before forcing "
 						 "log file rotation."),
-			NULL,
+			gettext_noop("0 disables time-based creation of new log files."),
 			GUC_UNIT_MIN
 		},
 		&Log_RotationAge,
@@ -3305,7 +3305,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_size", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the maximum size a log file can reach before "
 						 "being rotated."),
-			NULL,
+			gettext_noop("0 disables size-based creation of new log files."),
 			GUC_UNIT_KB
 		},
 		&Log_RotationSize,
@@ -3407,7 +3407,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_summary_keep_time", PGC_SIGHUP, WAL_SUMMARIZATION,
 			gettext_noop("Time for which WAL summary files should be kept."),
-			NULL,
+			gettext_noop("0 disables automatic summary file deletion."),
 			GUC_UNIT_MIN,
 		},
 		&wal_summary_keep_time,
@@ -3438,8 +3438,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_max_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum, or -1 to disable maximum threshold."),
-			NULL
+			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum."),
+			gettext_noop("-1 disables the maximum threshold.")
 		},
 		&autovacuum_vac_max_thresh,
 		100000000, -1, INT_MAX,
@@ -3447,8 +3447,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_insert_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Minimum number of tuple inserts prior to vacuum, or -1 to disable insert vacuums."),
-			NULL
+			gettext_noop("Minimum number of tuple inserts prior to vacuum."),
+			gettext_noop("-1 disables insert vacuums.")
 		},
 		&autovacuum_vac_ins_thresh,
 		1000, -1, INT_MAX,
@@ -3540,7 +3540,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_work_mem", PGC_SIGHUP, RESOURCES_MEM,
 			gettext_noop("Sets the maximum memory to be used by each autovacuum worker process."),
-			NULL,
+			gettext_noop("-1 means use \"maintenance_work_mem\"."),
 			GUC_UNIT_KB
 		},
 		&autovacuum_work_mem,
@@ -3551,7 +3551,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_idle", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between issuing TCP keepalives."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_idle,
@@ -3562,7 +3562,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between TCP keepalive retransmits."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_interval,
@@ -3585,8 +3585,8 @@ struct config_int ConfigureNamesInt[] =
 		{"tcp_keepalives_count", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Maximum number of TCP keepalive retransmits."),
 			gettext_noop("Number of consecutive keepalive retransmits that can be "
-						 "lost before a connection is considered dead. A value of 0 uses the "
-						 "system default."),
+						 "lost before a connection is considered dead. 0 "
+						 "means use the system default."),
 		},
 		&tcp_keepalives_count,
 		0, 0, INT_MAX,
@@ -3596,8 +3596,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"gin_fuzzy_search_limit", PGC_USERSET, CLIENT_CONN_OTHER,
 			gettext_noop("Sets the maximum allowed result for exact search by GIN."),
-			NULL,
-			0
+			gettext_noop("0 means no limit."),
 		},
 		&GinFuzzySearchLimit,
 		0, 0, INT_MAX,
@@ -3653,7 +3652,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"log_temp_files", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Log the use of temporary files larger than this number of kilobytes."),
-			gettext_noop("Zero logs all files. The default is -1 (turning this feature off)."),
+			gettext_noop("-1 disables logging temporary files. 0 means log all temporary files."),
 			GUC_UNIT_KB
 		},
 		&log_temp_files,
@@ -3686,7 +3685,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_user_timeout", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("TCP user timeout."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_MS
 		},
 		&tcp_user_timeout,
@@ -3697,7 +3696,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"huge_page_size", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("The size of huge page that should be requested."),
-			NULL,
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_KB
 		},
 		&huge_page_size,
@@ -3708,7 +3707,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"debug_discard_caches", PGC_SUSET, DEVELOPER_OPTIONS,
 			gettext_noop("Aggressively flush system caches for debugging purposes."),
-			NULL,
+			gettext_noop("0 means use normal caching behavior."),
 			GUC_NOT_IN_SAMPLE
 		},
 		&debug_discard_caches,
@@ -3731,7 +3730,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"client_connection_check_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Sets the time interval between checks for disconnection while running queries."),
-			NULL,
+			gettext_noop("0 disables connection checks."),
 			GUC_UNIT_MS
 		},
 		&client_connection_check_interval,
@@ -3743,7 +3742,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_startup_progress_interval", PGC_SIGHUP, LOGGING_WHEN,
 			gettext_noop("Time between progress updates for "
 						 "long-running startup operations."),
-			gettext_noop("0 turns this feature off."),
+			gettext_noop("0 disables progress updates."),
 			GUC_UNIT_MS,
 		},
 		&log_startup_progress_interval,
@@ -3974,7 +3973,7 @@ struct config_real ConfigureNamesReal[] =
 	{
 		{"autovacuum_vacuum_cost_delay", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost delay in milliseconds, for autovacuum."),
-			NULL,
+			gettext_noop("-1 means use \"vacuum_cost_delay\"."),
 			GUC_UNIT_MS
 		},
 		&autovacuum_vac_cost_delay,
@@ -4065,7 +4064,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_command", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the shell command that will be called to archive a WAL file."),
-			gettext_noop("This is used only if \"archive_library\" is not set.")
+			gettext_noop("An empty string means use \"archive_library\".")
 		},
 		&XLogArchiveCommand,
 		"",
@@ -4075,7 +4074,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_library", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the library that will be called to archive a WAL file."),
-			gettext_noop("An empty string indicates that \"archive_command\" should be used.")
+			gettext_noop("An empty string means use \"archive_command\".")
 		},
 		&XLogArchiveLibrary,
 		"",
@@ -4203,7 +4202,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"log_line_prefix", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Controls information prefixed to each log line."),
-			gettext_noop("If blank, no prefix is used.")
+			gettext_noop("An empty string means no prefix.")
 		},
 		&Log_line_prefix,
 		"%m [%p] ",
@@ -4246,7 +4245,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"default_tablespace", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the default tablespace to create tables and indexes in."),
-			gettext_noop("An empty string selects the database's default tablespace."),
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_IS_NAME
 		},
 		&default_tablespace,
@@ -4257,7 +4256,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"temp_tablespaces", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the tablespace(s) to use for temporary tables and sort files."),
-			NULL,
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_LIST_INPUT | GUC_LIST_QUOTE
 		},
 		&temp_tablespaces,
@@ -4269,7 +4268,7 @@ struct config_string ConfigureNamesString[] =
 		{"createrole_self_grant", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets whether a CREATEROLE user automatically grants "
 						 "the role to themselves, and with which options."),
-			NULL,
+			gettext_noop("An empty string disables automatic self grants."),
 			GUC_LIST_INPUT
 		},
 		&createrole_self_grant,
@@ -4305,7 +4304,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"bonjour_name", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the Bonjour service name."),
-			NULL
+			gettext_noop("An empty string means use the computer name.")
 		},
 		&bonjour_name,
 		"",
@@ -4315,7 +4314,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_messages", PGC_SUSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the language in which messages are displayed."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_messages,
 		"",
@@ -4325,7 +4324,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_monetary", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting monetary amounts."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_monetary,
 		"C",
@@ -4335,7 +4334,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_numeric", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting numbers."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_numeric,
 		"C",
@@ -4345,7 +4344,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_time", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting date and time values."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_time,
 		"C",
@@ -4524,7 +4523,8 @@ struct config_string ConfigureNamesString[] =
 		{"unix_socket_group", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the owning group of the Unix-domain socket."),
 			gettext_noop("The owning user of the socket is always the user "
-						 "that starts the server.")
+						 "that starts the server. An empty string means use "
+						 "the user's default group.")
 		},
 		&Unix_socket_group,
 		"",
@@ -4700,8 +4700,8 @@ struct config_string ConfigureNamesString[] =
 
 	{
 		{"ssl_tls13_ciphers", PGC_SIGHUP, CONN_AUTH_SSL,
-			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites (leave blank for default)."),
-			NULL,
+			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites."),
+			gettext_noop("An empty string means use the default cipher suites."),
 			GUC_SUPERUSER_ONLY
 		},
 		&SSLCipherSuites,
@@ -4742,7 +4742,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_dh_params_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL DH parameters file."),
-			NULL,
+			gettext_noop("An empty string means use compiled-in default parameters."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_dh_params_file,
@@ -4753,7 +4753,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_passphrase_command", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Command to obtain passphrases for SSL."),
-			NULL,
+			gettext_noop("An empty string means use the built-in prompting mechanism."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_passphrase_command,
@@ -4819,7 +4819,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"debug_io_direct", PGC_POSTMASTER, DEVELOPER_OPTIONS,
 			gettext_noop("Use direct I/O for file access."),
-			NULL,
+			gettext_noop("An empty string disables direct I/O."),
 			GUC_LIST_INPUT | GUC_NOT_IN_SAMPLE
 		},
 		&debug_io_direct_string,
diff --git a/src/include/utils/guc_tables.h b/src/include/utils/guc_tables.h
index 1c1c5b6ea52..c9935d00bee 100644
--- a/src/include/utils/guc_tables.h
+++ b/src/include/utils/guc_tables.h
@@ -138,6 +138,21 @@ typedef struct guc_stack
  * applications may use the long description as well, and will append
  * it to the short description. (separated by a newline or '. ')
  *
+ * If the GUC accepts a special value like -1 to disable the feature, use a
+ * system default, etc., it should be mentioned in the long description with
+ * the following style:
+ *
+ *  - Special values should be listed at the end of the long description.
+ *  - Descriptions should use numerals (e.g., "0") instead of words (e.g.,
+ *    "zero").
+ *  - Special value mentions should be concise and direct (e.g., "0 disables
+ *    the timeout.", "An empty string means use the operating system
+ *    setting.").
+ *  - Multiple special values should be listed in ascending order.
+ *
+ * However, special values should _not_ be mentioned if the description would
+ * be too complex or if the meaning is sufficiently obvious.
+ *
  * srole is the role that set the current value, or BOOTSTRAP_SUPERUSERID
  * if the value came from an internal source or the config file.  Similarly
  * for reset_srole (which is usually BOOTSTRAP_SUPERUSERID, but not always).
-- 
2.39.5 (Apple Git-154)

From 7526dcc25c992be8e2bc6aed2a030dcdd1d536e2 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Wed, 12 Feb 2025 14:26:00 -0600
Subject: [PATCH v7 1/1] Describe special values in GUC descriptions more
 consistently.

Many GUCs accept special values like -1 or an empty string to
disable the feature, use a system default, etc.  While the
documentation consistently lists these special values, the GUC
descriptions do not.  Many such descriptions fail to mention the
special values, and those that do vary in phrasing and placement.
This commit aims to bring some consistency to this area by applying
the following rules:

* Special values should be listed at the end of the long
  description.
* Descriptions should use numerals (e.g., "0") instead of words
  (e.g., "zero").
* Special value mentions should be concise and direct (e.g., "0
  disables the timeout.", "An empty string means use the operating
  system setting.").
* Multiple special values should be listed in ascending order.

Of course, there are exceptions, such as
max_pred_locks_per_relation and search_path, whose special values
are too complex to include.  And there are cases like
listen_addresses, where the meaning of an empty string is arguably
too obvious to include.  In those cases, I've refrained from adding
special value information to the GUC description.

Reviewed-by: Peter Smith <smithpb2250@gmail.com>
Reviewed-by: "David G. Johnston" <david.g.johnston@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Discussion: https://postgr.es/m/Z6aIy4aywxUZHAo6%40nathan
---
 src/backend/utils/misc/guc_tables.c | 139 ++++++++++++++--------------
 src/include/utils/guc_tables.h      |  15 +++
 2 files changed, 84 insertions(+), 70 deletions(-)

diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index 226af43fe23..42728189322 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -2119,7 +2119,7 @@ struct config_int ConfigureNamesInt[] =
 		{"archive_timeout", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the amount of time to wait before forcing a "
 						 "switch to the next WAL file."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_S
 		},
 		&XLogArchiveTimeout,
@@ -2196,7 +2196,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_pool_size", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of individuals in the population."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_pool_size,
@@ -2206,7 +2206,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"geqo_generations", PGC_USERSET, QUERY_TUNING_GEQO,
 			gettext_noop("GEQO: number of iterations of the algorithm."),
-			gettext_noop("Zero selects a suitable default value."),
+			gettext_noop("0 means use a suitable default value."),
 			GUC_EXPLAIN
 		},
 		&Geqo_generations,
@@ -2229,7 +2229,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_archive_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_archive_delay,
@@ -2240,7 +2240,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"max_standby_streaming_delay", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data."),
-			NULL,
+			gettext_noop("-1 means wait forever."),
 			GUC_UNIT_MS
 		},
 		&max_standby_streaming_delay,
@@ -2273,7 +2273,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_receiver_timeout", PGC_SIGHUP, REPLICATION_STANDBY,
 			gettext_noop("Sets the maximum wait time to receive data from the sending server."),
-			NULL,
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&wal_receiver_timeout,
@@ -2364,7 +2364,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"shared_memory_size_in_huge_pages", PGC_INTERNAL, PRESET_OPTIONS,
 			gettext_noop("Shows the number of huge pages needed for the main shared memory area."),
-			gettext_noop("-1 indicates that the value could not be determined."),
+			gettext_noop("-1 means huge pages are not supported."),
 			GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE | GUC_RUNTIME_COMPUTED
 		},
 		&shared_memory_size_in_huge_pages,
@@ -2386,7 +2386,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"commit_timestamp_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the commit timestamp cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&commit_timestamp_buffers,
@@ -2441,7 +2441,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"subtransaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the subtransaction cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&subtransaction_buffers,
@@ -2452,7 +2452,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_buffers", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("Sets the size of the dedicated buffer pool used for the transaction status cache."),
-			gettext_noop("Specify 0 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("0 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_BLOCKS
 		},
 		&transaction_buffers,
@@ -2636,7 +2636,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_vacuum_cost_limit", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost amount available before napping, for autovacuum."),
-			NULL
+			gettext_noop("-1 means use \"vacuum_cost_limit\".")
 		},
 		&autovacuum_vac_cost_limit,
 		-1, -1, 10000,
@@ -2692,7 +2692,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"statement_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any statement."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&StatementTimeout,
@@ -2703,7 +2703,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"lock_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any wait for a lock."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&LockTimeout,
@@ -2714,7 +2714,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_in_transaction_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleInTransactionSessionTimeout,
@@ -2725,7 +2725,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"transaction_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed duration of any transaction within a session (not a prepared transaction)."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&TransactionTimeout,
@@ -2736,7 +2736,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"idle_session_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the maximum allowed idle time between queries, when not in a transaction."),
-			gettext_noop("A value of 0 turns off the timeout."),
+			gettext_noop("0 disables the timeout."),
 			GUC_UNIT_MS
 		},
 		&IdleSessionTimeout,
@@ -2950,7 +2950,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Write a message to the server log if checkpoints "
 						 "caused by the filling of WAL segment files happen more "
 						 "frequently than this amount of time. "
-						 "Zero turns off the warning."),
+						 "0 disables the warning."),
 			GUC_UNIT_S
 		},
 		&CheckPointWarning,
@@ -2961,7 +2961,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"checkpoint_flush_after", PGC_SIGHUP, WAL_CHECKPOINTS,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&checkpoint_flush_after,
@@ -2972,7 +2972,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_buffers", PGC_POSTMASTER, WAL_SETTINGS,
 			gettext_noop("Sets the number of disk-page buffers in shared memory for WAL."),
-			gettext_noop("Specify -1 to have this value determined as a fraction of \"shared_buffers\"."),
+			gettext_noop("-1 means use a fraction of \"shared_buffers\"."),
 			GUC_UNIT_XBLOCKS
 		},
 		&XLOGbuffers,
@@ -3038,8 +3038,8 @@ struct config_int ConfigureNamesInt[] =
 		{"max_slot_wal_keep_size", PGC_SIGHUP, REPLICATION_SENDING,
 			gettext_noop("Sets the maximum WAL size that can be reserved by replication slots."),
 			gettext_noop("Replication slots will be marked as failed, and segments released "
-						 "for deletion or recycling, if this much space is occupied by WAL "
-						 "on disk."),
+						 "for deletion or recycling, if this much space is occupied by WAL on disk. "
+						 "-1 means no maximum."),
 			GUC_UNIT_MB
 		},
 		&max_slot_wal_keep_size_mb,
@@ -3099,7 +3099,7 @@ struct config_int ConfigureNamesInt[] =
 			gettext_noop("Sets the minimum execution time above which "
 						 "a sample of statements will be logged."
 						 " Sampling is determined by \"log_statement_sample_rate\"."),
-			gettext_noop("Zero logs a sample of all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables sampling. 0 means sample all statements."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_sample,
@@ -3111,7 +3111,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_min_duration_statement", PGC_SUSET, LOGGING_WHEN,
 			gettext_noop("Sets the minimum execution time above which "
 						 "all statements will be logged."),
-			gettext_noop("Zero prints all queries. -1 turns this feature off."),
+			gettext_noop("-1 disables logging statement durations. 0 means log all statement durations."),
 			GUC_UNIT_MS
 		},
 		&log_min_duration_statement,
@@ -3123,7 +3123,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_autovacuum_min_duration", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Sets the minimum execution time above which "
 						 "autovacuum actions will be logged."),
-			gettext_noop("Zero prints all actions. -1 turns autovacuum logging off."),
+			gettext_noop("-1 disables logging autovacuum actions. 0 means log all autovacuum actions."),
 			GUC_UNIT_MS
 		},
 		&Log_autovacuum_min_duration,
@@ -3135,7 +3135,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length,
@@ -3147,7 +3147,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_parameter_max_length_on_error", PGC_USERSET, LOGGING_WHAT,
 			gettext_noop("Sets the maximum length in bytes of data logged for bind "
 						 "parameter values when logging statements, on error."),
-			gettext_noop("-1 to print values in full."),
+			gettext_noop("-1 means log values in full."),
 			GUC_UNIT_BYTE
 		},
 		&log_parameter_max_length_on_error,
@@ -3169,7 +3169,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_lru_maxpages", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Background writer maximum number of LRU pages to flush per round."),
-			NULL
+			gettext_noop("0 disables background writing.")
 		},
 		&bgwriter_lru_maxpages,
 		100, 0, INT_MAX / 2,	/* Same upper limit as shared_buffers */
@@ -3179,7 +3179,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"bgwriter_flush_after", PGC_SIGHUP, RESOURCES_BGWRITER,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&bgwriter_flush_after,
@@ -3192,7 +3192,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_IO,
 			gettext_noop("Number of simultaneous requests that can be handled efficiently by the disk subsystem."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&effective_io_concurrency,
@@ -3206,7 +3206,7 @@ struct config_int ConfigureNamesInt[] =
 			PGC_USERSET,
 			RESOURCES_IO,
 			gettext_noop("A variant of \"effective_io_concurrency\" that is used for maintenance work."),
-			NULL,
+			gettext_noop("0 disables simultaneous requests."),
 			GUC_EXPLAIN
 		},
 		&maintenance_io_concurrency,
@@ -3233,7 +3233,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"backend_flush_after", PGC_USERSET, RESOURCES_IO,
 			gettext_noop("Number of pages after which previously performed writes are flushed to disk."),
-			NULL,
+			gettext_noop("0 disables forced writeback."),
 			GUC_UNIT_BLOCKS
 		},
 		&backend_flush_after,
@@ -3293,7 +3293,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_age", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the amount of time to wait before forcing "
 						 "log file rotation."),
-			NULL,
+			gettext_noop("0 disables time-based creation of new log files."),
 			GUC_UNIT_MIN
 		},
 		&Log_RotationAge,
@@ -3305,7 +3305,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_rotation_size", PGC_SIGHUP, LOGGING_WHERE,
 			gettext_noop("Sets the maximum size a log file can reach before "
 						 "being rotated."),
-			NULL,
+			gettext_noop("0 disables size-based creation of new log files."),
 			GUC_UNIT_KB
 		},
 		&Log_RotationSize,
@@ -3407,7 +3407,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"wal_summary_keep_time", PGC_SIGHUP, WAL_SUMMARIZATION,
 			gettext_noop("Time for which WAL summary files should be kept."),
-			NULL,
+			gettext_noop("0 disables automatic summary file deletion."),
 			GUC_UNIT_MIN,
 		},
 		&wal_summary_keep_time,
@@ -3438,8 +3438,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_max_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum, or -1 to disable maximum threshold."),
-			NULL
+			gettext_noop("Maximum number of tuple updates or deletes prior to vacuum."),
+			gettext_noop("-1 disables the maximum threshold.")
 		},
 		&autovacuum_vac_max_thresh,
 		100000000, -1, INT_MAX,
@@ -3447,8 +3447,8 @@ struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"autovacuum_vacuum_insert_threshold", PGC_SIGHUP, VACUUM_AUTOVACUUM,
-			gettext_noop("Minimum number of tuple inserts prior to vacuum, or -1 to disable insert vacuums."),
-			NULL
+			gettext_noop("Minimum number of tuple inserts prior to vacuum."),
+			gettext_noop("-1 disables insert vacuums.")
 		},
 		&autovacuum_vac_ins_thresh,
 		1000, -1, INT_MAX,
@@ -3540,7 +3540,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"autovacuum_work_mem", PGC_SIGHUP, RESOURCES_MEM,
 			gettext_noop("Sets the maximum memory to be used by each autovacuum worker process."),
-			NULL,
+			gettext_noop("-1 means use \"maintenance_work_mem\"."),
 			GUC_UNIT_KB
 		},
 		&autovacuum_work_mem,
@@ -3551,7 +3551,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_idle", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between issuing TCP keepalives."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_idle,
@@ -3562,7 +3562,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_keepalives_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Time between TCP keepalive retransmits."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_S
 		},
 		&tcp_keepalives_interval,
@@ -3585,8 +3585,8 @@ struct config_int ConfigureNamesInt[] =
 		{"tcp_keepalives_count", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Maximum number of TCP keepalive retransmits."),
 			gettext_noop("Number of consecutive keepalive retransmits that can be "
-						 "lost before a connection is considered dead. A value of 0 uses the "
-						 "system default."),
+						 "lost before a connection is considered dead. "
+						 "0 means use the system default."),
 		},
 		&tcp_keepalives_count,
 		0, 0, INT_MAX,
@@ -3596,8 +3596,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"gin_fuzzy_search_limit", PGC_USERSET, CLIENT_CONN_OTHER,
 			gettext_noop("Sets the maximum allowed result for exact search by GIN."),
-			NULL,
-			0
+			gettext_noop("0 means no limit."),
 		},
 		&GinFuzzySearchLimit,
 		0, 0, INT_MAX,
@@ -3653,7 +3652,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"log_temp_files", PGC_SUSET, LOGGING_WHAT,
 			gettext_noop("Log the use of temporary files larger than this number of kilobytes."),
-			gettext_noop("Zero logs all files. The default is -1 (turning this feature off)."),
+			gettext_noop("-1 disables logging temporary files. 0 means log all temporary files."),
 			GUC_UNIT_KB
 		},
 		&log_temp_files,
@@ -3686,7 +3685,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"tcp_user_timeout", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("TCP user timeout."),
-			gettext_noop("A value of 0 uses the system default."),
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_MS
 		},
 		&tcp_user_timeout,
@@ -3697,7 +3696,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"huge_page_size", PGC_POSTMASTER, RESOURCES_MEM,
 			gettext_noop("The size of huge page that should be requested."),
-			NULL,
+			gettext_noop("0 means use the system default."),
 			GUC_UNIT_KB
 		},
 		&huge_page_size,
@@ -3708,7 +3707,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"debug_discard_caches", PGC_SUSET, DEVELOPER_OPTIONS,
 			gettext_noop("Aggressively flush system caches for debugging purposes."),
-			NULL,
+			gettext_noop("0 means use normal caching behavior."),
 			GUC_NOT_IN_SAMPLE
 		},
 		&debug_discard_caches,
@@ -3731,7 +3730,7 @@ struct config_int ConfigureNamesInt[] =
 	{
 		{"client_connection_check_interval", PGC_USERSET, CONN_AUTH_TCP,
 			gettext_noop("Sets the time interval between checks for disconnection while running queries."),
-			NULL,
+			gettext_noop("0 disables connection checks."),
 			GUC_UNIT_MS
 		},
 		&client_connection_check_interval,
@@ -3743,7 +3742,7 @@ struct config_int ConfigureNamesInt[] =
 		{"log_startup_progress_interval", PGC_SIGHUP, LOGGING_WHEN,
 			gettext_noop("Time between progress updates for "
 						 "long-running startup operations."),
-			gettext_noop("0 turns this feature off."),
+			gettext_noop("0 disables progress updates."),
 			GUC_UNIT_MS,
 		},
 		&log_startup_progress_interval,
@@ -3974,7 +3973,7 @@ struct config_real ConfigureNamesReal[] =
 	{
 		{"autovacuum_vacuum_cost_delay", PGC_SIGHUP, VACUUM_AUTOVACUUM,
 			gettext_noop("Vacuum cost delay in milliseconds, for autovacuum."),
-			NULL,
+			gettext_noop("-1 means use \"vacuum_cost_delay\"."),
 			GUC_UNIT_MS
 		},
 		&autovacuum_vac_cost_delay,
@@ -4065,7 +4064,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_command", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the shell command that will be called to archive a WAL file."),
-			gettext_noop("This is used only if \"archive_library\" is not set.")
+			gettext_noop("An empty string means use \"archive_library\".")
 		},
 		&XLogArchiveCommand,
 		"",
@@ -4075,7 +4074,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"archive_library", PGC_SIGHUP, WAL_ARCHIVING,
 			gettext_noop("Sets the library that will be called to archive a WAL file."),
-			gettext_noop("An empty string indicates that \"archive_command\" should be used.")
+			gettext_noop("An empty string means use \"archive_command\".")
 		},
 		&XLogArchiveLibrary,
 		"",
@@ -4203,7 +4202,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"log_line_prefix", PGC_SIGHUP, LOGGING_WHAT,
 			gettext_noop("Controls information prefixed to each log line."),
-			gettext_noop("If blank, no prefix is used.")
+			gettext_noop("An empty string means no prefix.")
 		},
 		&Log_line_prefix,
 		"%m [%p] ",
@@ -4246,7 +4245,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"default_tablespace", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the default tablespace to create tables and indexes in."),
-			gettext_noop("An empty string selects the database's default tablespace."),
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_IS_NAME
 		},
 		&default_tablespace,
@@ -4257,7 +4256,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"temp_tablespaces", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets the tablespace(s) to use for temporary tables and sort files."),
-			NULL,
+			gettext_noop("An empty string means use the database's default tablespace."),
 			GUC_LIST_INPUT | GUC_LIST_QUOTE
 		},
 		&temp_tablespaces,
@@ -4269,7 +4268,7 @@ struct config_string ConfigureNamesString[] =
 		{"createrole_self_grant", PGC_USERSET, CLIENT_CONN_STATEMENT,
 			gettext_noop("Sets whether a CREATEROLE user automatically grants "
 						 "the role to themselves, and with which options."),
-			NULL,
+			gettext_noop("An empty string disables automatic self grants."),
 			GUC_LIST_INPUT
 		},
 		&createrole_self_grant,
@@ -4305,7 +4304,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"bonjour_name", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the Bonjour service name."),
-			NULL
+			gettext_noop("An empty string means use the computer name.")
 		},
 		&bonjour_name,
 		"",
@@ -4315,7 +4314,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_messages", PGC_SUSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the language in which messages are displayed."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_messages,
 		"",
@@ -4325,7 +4324,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_monetary", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting monetary amounts."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_monetary,
 		"C",
@@ -4335,7 +4334,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_numeric", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting numbers."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_numeric,
 		"C",
@@ -4345,7 +4344,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"lc_time", PGC_USERSET, CLIENT_CONN_LOCALE,
 			gettext_noop("Sets the locale for formatting date and time values."),
-			NULL
+			gettext_noop("An empty string means use the operating system setting.")
 		},
 		&locale_time,
 		"C",
@@ -4523,8 +4522,8 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"unix_socket_group", PGC_POSTMASTER, CONN_AUTH_SETTINGS,
 			gettext_noop("Sets the owning group of the Unix-domain socket."),
-			gettext_noop("The owning user of the socket is always the user "
-						 "that starts the server.")
+			gettext_noop("The owning user of the socket is always the user that starts the server. "
+						 "An empty string means use the user's default group.")
 		},
 		&Unix_socket_group,
 		"",
@@ -4700,8 +4699,8 @@ struct config_string ConfigureNamesString[] =
 
 	{
 		{"ssl_tls13_ciphers", PGC_SIGHUP, CONN_AUTH_SSL,
-			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites (leave blank for default)."),
-			NULL,
+			gettext_noop("Sets the list of allowed TLSv1.3 cipher suites."),
+			gettext_noop("An empty string means use the default cipher suites."),
 			GUC_SUPERUSER_ONLY
 		},
 		&SSLCipherSuites,
@@ -4742,7 +4741,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_dh_params_file", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Location of the SSL DH parameters file."),
-			NULL,
+			gettext_noop("An empty string means use compiled-in default parameters."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_dh_params_file,
@@ -4753,7 +4752,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"ssl_passphrase_command", PGC_SIGHUP, CONN_AUTH_SSL,
 			gettext_noop("Command to obtain passphrases for SSL."),
-			NULL,
+			gettext_noop("An empty string means use the built-in prompting mechanism."),
 			GUC_SUPERUSER_ONLY
 		},
 		&ssl_passphrase_command,
@@ -4819,7 +4818,7 @@ struct config_string ConfigureNamesString[] =
 	{
 		{"debug_io_direct", PGC_POSTMASTER, DEVELOPER_OPTIONS,
 			gettext_noop("Use direct I/O for file access."),
-			NULL,
+			gettext_noop("An empty string disables direct I/O."),
 			GUC_LIST_INPUT | GUC_NOT_IN_SAMPLE
 		},
 		&debug_io_direct_string,
diff --git a/src/include/utils/guc_tables.h b/src/include/utils/guc_tables.h
index 1c1c5b6ea52..c9935d00bee 100644
--- a/src/include/utils/guc_tables.h
+++ b/src/include/utils/guc_tables.h
@@ -138,6 +138,21 @@ typedef struct guc_stack
  * applications may use the long description as well, and will append
  * it to the short description. (separated by a newline or '. ')
  *
+ * If the GUC accepts a special value like -1 to disable the feature, use a
+ * system default, etc., it should be mentioned in the long description with
+ * the following style:
+ *
+ *  - Special values should be listed at the end of the long description.
+ *  - Descriptions should use numerals (e.g., "0") instead of words (e.g.,
+ *    "zero").
+ *  - Special value mentions should be concise and direct (e.g., "0 disables
+ *    the timeout.", "An empty string means use the operating system
+ *    setting.").
+ *  - Multiple special values should be listed in ascending order.
+ *
+ * However, special values should _not_ be mentioned if the description would
+ * be too complex or if the meaning is sufficiently obvious.
+ *
  * srole is the role that set the current value, or BOOTSTRAP_SUPERUSERID
  * if the value came from an internal source or the config file.  Similarly
  * for reset_srole (which is usually BOOTSTRAP_SUPERUSERID, but not always).
-- 
2.39.5 (Apple Git-154)

From 71274740583fcac642b6e74adabeeaf3992f2e1a Mon Sep 17 00:00:00 2001
From: Ilia Evdokimov <ilya.evdokimov@tantorlabs.ru>
Date: Mon, 17 Feb 2025 12:47:43 +0300
Subject: [PATCH v8] Standardize parameter descriptions in auto_explain

Align the descriptions of log_min_duration and log_parameter_max_length
in auto_explain with the formatting conventions used for other GUC parameters
according to 977d865 commit.
---
 contrib/auto_explain/auto_explain.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/contrib/auto_explain/auto_explain.c b/contrib/auto_explain/auto_explain.c
index f1ad876e82..912abc42e8 100644
--- a/contrib/auto_explain/auto_explain.c
+++ b/contrib/auto_explain/auto_explain.c
@@ -93,7 +93,7 @@ _PG_init(void)
 	/* Define custom GUC variables. */
 	DefineCustomIntVariable("auto_explain.log_min_duration",
 							"Sets the minimum execution time above which plans will be logged.",
-							"Zero prints all plans. -1 turns this feature off.",
+							"0 prints all plans. -1 turns this feature off.",
 							&auto_explain_log_min_duration,
 							-1,
 							-1, INT_MAX,
@@ -105,7 +105,7 @@ _PG_init(void)
 
 	DefineCustomIntVariable("auto_explain.log_parameter_max_length",
 							"Sets the maximum length of query parameters to log.",
-							"Zero logs no query parameters, -1 logs them in full.",
+							"0 logs no query parameters, -1 logs them in full.",
 							&auto_explain_log_parameter_max_length,
 							-1,
 							-1, INT_MAX,
-- 
2.34.1

From 44f60949a4636eb649d29d752a55a8410213d12e Mon Sep 17 00:00:00 2001
From: Ilia Evdokimov <ilya.evdokimov@tantorlabs.com>
Date: Tue, 18 Feb 2025 01:02:15 +0300
Subject: [PATCH v9] Standardize parameter descriptions in auto_explain

Align the descriptions of log_min_duration and log_parameter_max_length
in auto_explain with the formatting conventions used for other GUC parameters,
as established in commit 977d865.

Remove the description of the zero value for log_parameter_max_length,
as there are numerous examples of similar "max" GUC parameters that
do not explicitly mention zero, as its meaning is considered clear.
---
 contrib/auto_explain/auto_explain.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/contrib/auto_explain/auto_explain.c b/contrib/auto_explain/auto_explain.c
index f1ad876e82..1c6f840e30 100644
--- a/contrib/auto_explain/auto_explain.c
+++ b/contrib/auto_explain/auto_explain.c
@@ -93,7 +93,7 @@ _PG_init(void)
 	/* Define custom GUC variables. */
 	DefineCustomIntVariable("auto_explain.log_min_duration",
 							"Sets the minimum execution time above which plans will be logged.",
-							"Zero prints all plans. -1 turns this feature off.",
+							"-1 disables logging plans. 0 means log all plans.",
 							&auto_explain_log_min_duration,
 							-1,
 							-1, INT_MAX,
@@ -105,7 +105,7 @@ _PG_init(void)
 
 	DefineCustomIntVariable("auto_explain.log_parameter_max_length",
 							"Sets the maximum length of query parameters to log.",
-							"Zero logs no query parameters, -1 logs them in full.",
+							"-1 means log parameter values in full.",
 							&auto_explain_log_parameter_max_length,
 							-1,
 							-1, INT_MAX,
-- 
2.34.1