Various improvements to the GUC description strings. Punctuate and

capitalize the strings like sentences. Remove unnecessarily
specific descriptions of the units used by GUC variables, since
we now allow any reasonable unit to be specified.

Author: Neil Conway

src/backend/utils/misc/guc.c

@@ -10,7 +10,7 @@
  * Written by Peter Eisentraut <peter_e@gmx.net>.
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/utils/misc/guc.c,v 1.360 2006/11/29 14:50:07 petere Exp $
+ *	  $PostgreSQL: pgsql/src/backend/utils/misc/guc.c,v 1.361 2006/12/06 17:35:49 neilc Exp $
  *
  *--------------------------------------------------------------------
  */
@@ -587,7 +587,7 @@ static struct config_bool ConfigureNamesBool[] =
 	{
 		/* currently undocumented, so don't show in SHOW ALL */
 		{"exit_on_error", PGC_USERSET, UNGROUPED,
-			gettext_noop("no description available"),
+			gettext_noop("No description available."),
 			NULL,
 			GUC_NO_SHOW_ALL | GUC_NOT_IN_SAMPLE
 		},
@@ -669,7 +669,7 @@ static struct config_bool ConfigureNamesBool[] =
 #ifdef BTREE_BUILD_STATS
 	{
 		{"log_btree_build_stats", PGC_SUSET, DEVELOPER_OPTIONS,
-			gettext_noop("no description available"),
+			gettext_noop("No description available."),
 			NULL,
 			GUC_NOT_IN_SAMPLE
 		},
@@ -761,7 +761,7 @@ static struct config_bool ConfigureNamesBool[] =
 #ifdef LOCK_DEBUG
 	{
 		{"trace_locks", PGC_SUSET, DEVELOPER_OPTIONS,
-			gettext_noop("no description available"),
+			gettext_noop("No description available."),
 			NULL,
 			GUC_NOT_IN_SAMPLE
 		},
@@ -770,7 +770,7 @@ static struct config_bool ConfigureNamesBool[] =
 	},
 	{
 		{"trace_userlocks", PGC_SUSET, DEVELOPER_OPTIONS,
-			gettext_noop("no description available"),
+			gettext_noop("No description available."),
 			NULL,
 			GUC_NOT_IN_SAMPLE
 		},
@@ -779,7 +779,7 @@ static struct config_bool ConfigureNamesBool[] =
 	},
 	{
 		{"trace_lwlocks", PGC_SUSET, DEVELOPER_OPTIONS,
-			gettext_noop("no description available"),
+			gettext_noop("No description available."),
 			NULL,
 			GUC_NOT_IN_SAMPLE
 		},
@@ -788,7 +788,7 @@ static struct config_bool ConfigureNamesBool[] =
 	},
 	{
 		{"debug_deadlocks", PGC_SUSET, DEVELOPER_OPTIONS,
-			gettext_noop("no description available"),
+			gettext_noop("No description available."),
 			NULL,
 			GUC_NOT_IN_SAMPLE
 		},
@@ -982,7 +982,7 @@ static struct config_bool ConfigureNamesBool[] =
 
 	{
 		{"standard_conforming_strings", PGC_USERSET, COMPAT_OPTIONS_PREVIOUS,
-			gettext_noop("'...' strings treat backslashes literally."),
+			gettext_noop("Causes '...' strings to treat backslashes literally."),
 			NULL,
 			GUC_REPORT
 		},
@@ -1050,8 +1050,8 @@ static struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"from_collapse_limit", PGC_USERSET, QUERY_TUNING_OTHER,
-			gettext_noop("Sets the FROM-list size beyond which subqueries are not "
-						 "collapsed."),
+			gettext_noop("Sets the FROM-list size beyond which subqueries "
+						 "are not collapsed."),
 			gettext_noop("The planner will merge subqueries into upper "
 				"queries if the resulting FROM list would have no more than "
 						 "this many items.")
@@ -1061,11 +1061,11 @@ static struct config_int ConfigureNamesInt[] =
 	},
 	{
 		{"join_collapse_limit", PGC_USERSET, QUERY_TUNING_OTHER,
-			gettext_noop("Sets the FROM-list size beyond which JOIN constructs are not "
-						 "flattened."),
+			gettext_noop("Sets the FROM-list size beyond which JOIN "
+						 "constructs are not flattened."),
 			gettext_noop("The planner will flatten explicit JOIN "
-			"constructs into lists of FROM items whenever a list of no more "
-						 "than this many items would result.")
+						 "constructs into lists of FROM items whenever a "
+						 "list of no more than this many items would result.")
 		},
 		&join_collapse_limit,
 		8, 1, INT_MAX, NULL, NULL
@@ -1105,7 +1105,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"deadlock_timeout", PGC_SIGHUP, LOCK_MANAGEMENT,
-			gettext_noop("The time in milliseconds to wait on lock before checking for deadlock."),
+			gettext_noop("Sets the time to wait on a lock before checking for deadlock."),
 			NULL,
 			GUC_UNIT_MS
 		},
@@ -1322,7 +1322,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"statement_timeout", PGC_USERSET, CLIENT_CONN_STATEMENT,
-			gettext_noop("Sets the maximum allowed duration (in milliseconds) of any statement."),
+			gettext_noop("Sets the maximum allowed duration of any statement."),
 			gettext_noop("A value of 0 turns off the timeout."),
 			GUC_UNIT_MS
 		},
@@ -1369,7 +1369,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"authentication_timeout", PGC_SIGHUP, CONN_AUTH_SECURITY,
-			gettext_noop("Sets the maximum time in seconds to complete client authentication."),
+			gettext_noop("Sets the maximum allowed time to complete client authentication."),
 			NULL,
 			GUC_UNIT_S
 		},
@@ -1380,8 +1380,8 @@ static struct config_int ConfigureNamesInt[] =
 	{
 		/* Not for general use */
 		{"pre_auth_delay", PGC_SIGHUP, DEVELOPER_OPTIONS,
-			gettext_noop("no description available"),
-			NULL,
+			gettext_noop("Waits N seconds on connection startup before authentication."),
+			gettext_noop("This allows attaching a debugger to the process."),
 			GUC_NOT_IN_SAMPLE | GUC_UNIT_S
 		},
 		&PreAuthDelay,
@@ -1399,7 +1399,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"checkpoint_timeout", PGC_SIGHUP, WAL_CHECKPOINTS,
-			gettext_noop("Sets the maximum time in seconds between automatic WAL checkpoints."),
+			gettext_noop("Sets the maximum time between automatic WAL checkpoints."),
 			NULL,
 			GUC_UNIT_S
 		},
@@ -1409,8 +1409,8 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"checkpoint_warning", PGC_SIGHUP, WAL_CHECKPOINTS,
-			gettext_noop("Logs if filling of checkpoint segments happens more "
-						 "frequently than this (in seconds)."),
+			gettext_noop("Enables warnings if checkpoint segments are filled more "
+						 "frequently than this."),
 			gettext_noop("Write a message to the server log if checkpoints "
 			"caused by the filling of checkpoint segment files happens more "
 						 "frequently than this number of seconds. Zero turns off the warning."),
@@ -1463,7 +1463,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"log_min_duration_statement", PGC_SUSET, LOGGING_WHEN,
-			gettext_noop("Sets the minimum execution time in milliseconds above which statements will "
+			gettext_noop("Sets the minimum execution time above which statements will "
 						 "be logged."),
 			gettext_noop("Zero prints all queries. The default is -1 (turning this feature off)."),
 			GUC_UNIT_MS
@@ -1474,7 +1474,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"bgwriter_delay", PGC_SIGHUP, RESOURCES,
-			gettext_noop("Background writer sleep time between rounds in milliseconds"),
+			gettext_noop("Background writer sleep time between rounds."),
 			NULL,
 			GUC_UNIT_MS
 		},
@@ -1484,7 +1484,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"bgwriter_lru_maxpages", PGC_SIGHUP, RESOURCES,
-			gettext_noop("Background writer maximum number of LRU pages to flush per round"),
+			gettext_noop("Background writer maximum number of LRU pages to flush per round."),
 			NULL
 		},
 		&bgwriter_lru_maxpages,
@@ -1493,7 +1493,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"bgwriter_all_maxpages", PGC_SIGHUP, RESOURCES,
-			gettext_noop("Background writer maximum number of all pages to flush per round"),
+			gettext_noop("Background writer maximum number of all pages to flush per round."),
 			NULL
 		},
 		&bgwriter_all_maxpages,
@@ -1502,7 +1502,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"log_rotation_age", PGC_SIGHUP, LOGGING_WHERE,
-			gettext_noop("Automatic log file rotation will occur after N minutes"),
+			gettext_noop("Automatic log file rotation will occur after N minutes."),
 			NULL,
 			GUC_UNIT_MIN
 		},
@@ -1512,7 +1512,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"log_rotation_size", PGC_SIGHUP, LOGGING_WHERE,
-			gettext_noop("Automatic log file rotation will occur after N kilobytes"),
+			gettext_noop("Automatic log file rotation will occur after N kilobytes."),
 			NULL,
 			GUC_UNIT_KB
 		},
@@ -1542,7 +1542,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"max_identifier_length", PGC_INTERNAL, PRESET_OPTIONS,
-			gettext_noop("Shows the maximum identifier length"),
+			gettext_noop("Shows the maximum identifier length."),
 			NULL,
 			GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
 		},
@@ -1552,7 +1552,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"block_size", PGC_INTERNAL, PRESET_OPTIONS,
-			gettext_noop("Shows size of a disk block"),
+			gettext_noop("Shows the size of a disk block."),
 			NULL,
 			GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
 		},
@@ -1562,7 +1562,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"autovacuum_naptime", PGC_SIGHUP, AUTOVACUUM,
-			gettext_noop("Time to sleep between autovacuum runs, in seconds."),
+			gettext_noop("Time to sleep between autovacuum runs."),
 			NULL,
 			GUC_UNIT_S
 		},
@@ -1597,7 +1597,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"tcp_keepalives_idle", PGC_USERSET, CLIENT_CONN_OTHER,
-			gettext_noop("Seconds between issuing TCP keepalives."),
+			gettext_noop("Time between issuing TCP keepalives."),
 			gettext_noop("A value of 0 uses the system default."),
 			GUC_UNIT_S
 		},
@@ -1607,7 +1607,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"tcp_keepalives_interval", PGC_USERSET, CLIENT_CONN_OTHER,
-			gettext_noop("Seconds between TCP keepalive retransmits."),
+			gettext_noop("Time between TCP keepalive retransmits."),
 			gettext_noop("A value of 0 uses the system default."),
 			GUC_UNIT_S
 		},
@@ -1638,7 +1638,7 @@ static struct config_int ConfigureNamesInt[] =
 
 	{
 		{"effective_cache_size", PGC_USERSET, QUERY_TUNING_COST,
-			gettext_noop("Sets the planner's assumption about size of the disk cache."),
+			gettext_noop("Sets the planner's assumption about the size of the disk cache."),
 			gettext_noop("That is, the portion of the kernel's disk cache that "
 						 "will be used for PostgreSQL data files. This is measured in disk "
 						 "pages, which are normally 8 kB each."),
@@ -1726,7 +1726,7 @@ static struct config_real ConfigureNamesReal[] =
 
 	{
 		{"bgwriter_lru_percent", PGC_SIGHUP, RESOURCES,
-			gettext_noop("Background writer percentage of LRU buffers to flush per round"),
+			gettext_noop("Background writer percentage of LRU buffers to flush per round."),
 			NULL
 		},
 		&bgwriter_lru_percent,
@@ -1735,7 +1735,7 @@ static struct config_real ConfigureNamesReal[] =
 
 	{
 		{"bgwriter_all_percent", PGC_SIGHUP, RESOURCES,
-			gettext_noop("Background writer percentage of all buffers to flush per round"),
+			gettext_noop("Background writer percentage of all buffers to flush per round."),
 			NULL
 		},
 		&bgwriter_all_percent,
@@ -1780,8 +1780,8 @@ static struct config_string ConfigureNamesString[] =
 {
 	{
 		{"archive_command", PGC_SIGHUP, WAL_SETTINGS,
-			gettext_noop("WAL archiving command."),
-			gettext_noop("The shell command that will be called to archive a WAL file.")
+			gettext_noop("Sets the shell command that will be called to archive a WAL file."),
+			NULL
 		},
 		&XLogArchiveCommand,
 		"", NULL, NULL
@@ -1858,8 +1858,8 @@ static 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("Controls information prefixed to each log line."),
+			gettext_noop("If blank, no prefix is used.")
 		},
 		&Log_line_prefix,
 		"", NULL, NULL
@@ -2150,7 +2150,7 @@ static struct config_string ConfigureNamesString[] =
 	},
 	{
 		{"timezone_abbreviations", PGC_USERSET, CLIENT_CONN_LOCALE,
-			gettext_noop("Selects a file of time zone abbreviations"),
+			gettext_noop("Selects a file of time zone abbreviations."),
 			NULL,
 		},
 		&timezone_abbreviations_string,
@@ -2170,8 +2170,8 @@ static 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.")
 		},
 		&Unix_socket_group,
 		"", NULL, NULL
@@ -2199,7 +2199,7 @@ static struct config_string ConfigureNamesString[] =
 
 	{
 		{"wal_sync_method", PGC_SIGHUP, WAL_SETTINGS,
-			gettext_noop("Selects the method used for forcing WAL updates out to disk."),
+			gettext_noop("Selects the method used for forcing WAL updates to disk."),
 			NULL
 		},
 		&XLOG_sync_method,
@@ -2238,7 +2238,7 @@ static struct config_string ConfigureNamesString[] =
 
 	{
 		{"hba_file", PGC_POSTMASTER, FILE_LOCATIONS,
-			gettext_noop("Sets the server's \"hba\" configuration file"),
+			gettext_noop("Sets the server's \"hba\" configuration file."),
 			NULL,
 			GUC_SUPERUSER_ONLY
 		},
@@ -2248,7 +2248,7 @@ static struct config_string ConfigureNamesString[] =
 
 	{
 		{"ident_file", PGC_POSTMASTER, FILE_LOCATIONS,
-			gettext_noop("Sets the server's \"ident\" configuration file"),
+			gettext_noop("Sets the server's \"ident\" configuration file."),
 			NULL,
 			GUC_SUPERUSER_ONLY
 		},