]> granicus.if.org Git - postgresql/commitdiff
Reformat psql's --help=variables output.
authorTom Lane <tgl@sss.pgh.pa.us>
Tue, 5 Sep 2017 14:17:10 +0000 (10:17 -0400)
committerTom Lane <tgl@sss.pgh.pa.us>
Tue, 5 Sep 2017 14:17:10 +0000 (10:17 -0400)
The previous format with variable names and descriptions in separate
columns was extremely constraining about the length of the descriptions.
We'd dealt with that in several inconsistent ways over the years,
including letting the lines run over 80 characters, breaking descriptions
into multiple lines, or shoving the description onto a separate line.
But it's been a long time since the output could realistically fit onto
a single screen vertically, so let's just rely even more heavily on the
pager to deal with the vertical distance, and split each entry into two
(or more) lines, in the format

  variable-name
    variable description goes here

Each variable name + description remains a single translatable string,
in hopes of reducing translator confusion; we're just changing the
embedded whitespace.

I failed to resist the temptation to copy-edit one or two of the
descriptions while at it.

Discussion: https://postgr.es/m/2947.1504542679@sss.pgh.pa.us

src/bin/psql/help.c

index b3dbb5946eac091535a2d210f717d83047184b8d..b8cc9d33b898eca144af7ec04c8937f28849b99e 100644 (file)
@@ -336,7 +336,7 @@ helpVariables(unsigned short int pager)
         * Windows builds currently print one more line than non-Windows builds.
         * Using the larger number is fine.
         */
-       output = PageOutput(88, pager ? &(pset.popt.topt) : NULL);
+       output = PageOutput(140, pager ? &(pset.popt.topt) : NULL);
 
        fprintf(output, _("List of specially treated variables\n\n"));
 
@@ -344,62 +344,102 @@ helpVariables(unsigned short int pager)
        fprintf(output, _("Usage:\n"));
        fprintf(output, _("  psql --set=NAME=VALUE\n  or \\set NAME VALUE inside psql\n\n"));
 
-       fprintf(output, _("  AUTOCOMMIT         if set, successful SQL commands are automatically committed\n"));
-       fprintf(output, _("  COMP_KEYWORD_CASE  determines the case used to complete SQL key words\n"
-                                         "                     [lower, upper, preserve-lower, preserve-upper]\n"));
-       fprintf(output, _("  DBNAME             the currently connected database name\n"));
-       fprintf(output, _("  ECHO               controls what input is written to standard output\n"
-                                         "                     [all, errors, none, queries]\n"));
-       fprintf(output, _("  ECHO_HIDDEN        if set, display internal queries executed by backslash commands;\n"
-                                         "                     if set to \"noexec\", just show without execution\n"));
-       fprintf(output, _("  ENCODING           current client character set encoding\n"));
-       fprintf(output, _("  FETCH_COUNT        the number of result rows to fetch and display at a time\n"
-                                         "                     (default: 0=unlimited)\n"));
-       fprintf(output, _("  HISTCONTROL        controls command history [ignorespace, ignoredups, ignoreboth]\n"));
-       fprintf(output, _("  HISTFILE           file name used to store the command history\n"));
-       fprintf(output, _("  HISTSIZE           max number of commands to store in the command history\n"));
-       fprintf(output, _("  HOST               the currently connected database server host\n"));
-       fprintf(output, _("  IGNOREEOF          number of EOFs needed to terminate an interactive session\n"));
-       fprintf(output, _("  LASTOID            value of the last affected OID\n"));
-       fprintf(output, _("  ON_ERROR_ROLLBACK  if set, an error doesn't stop a transaction (uses implicit savepoints)\n"));
-       fprintf(output, _("  ON_ERROR_STOP      stop batch execution after error\n"));
-       fprintf(output, _("  PORT               server port of the current connection\n"));
-       fprintf(output, _("  PROMPT1            specifies the standard psql prompt\n"));
-       fprintf(output, _("  PROMPT2            specifies the prompt used when a statement continues from a previous line\n"));
-       fprintf(output, _("  PROMPT3            specifies the prompt used during COPY ... FROM STDIN\n"));
-       fprintf(output, _("  QUIET              run quietly (same as -q option)\n"));
-       fprintf(output, _("  SHOW_CONTEXT       controls display of message context fields [never, errors, always]\n"));
-       fprintf(output, _("  SINGLELINE         end of line terminates SQL command mode (same as -S option)\n"));
-       fprintf(output, _("  SINGLESTEP         single-step mode (same as -s option)\n"));
-       fprintf(output, _("  USER               the currently connected database user\n"));
-       fprintf(output, _("  VERBOSITY          controls verbosity of error reports [default, verbose, terse]\n"));
+       fprintf(output, _("  AUTOCOMMIT\n"
+                                         "    if set, successful SQL commands are automatically committed\n"));
+       fprintf(output, _("  COMP_KEYWORD_CASE\n"
+                                         "    determines the case used to complete SQL key words\n"
+                                         "    [lower, upper, preserve-lower, preserve-upper]\n"));
+       fprintf(output, _("  DBNAME\n"
+                                         "    the currently connected database name\n"));
+       fprintf(output, _("  ECHO\n"
+                                         "    controls what input is written to standard output\n"
+                                         "    [all, errors, none, queries]\n"));
+       fprintf(output, _("  ECHO_HIDDEN\n"
+                                         "    if set, display internal queries executed by backslash commands;\n"
+                                         "    if set to \"noexec\", just show them without execution\n"));
+       fprintf(output, _("  ENCODING\n"
+                                         "    current client character set encoding\n"));
+       fprintf(output, _("  FETCH_COUNT\n"
+                                         "    the number of result rows to fetch and display at a time (0 = unlimited)\n"));
+       fprintf(output, _("  HISTCONTROL\n"
+                                         "    controls command history [ignorespace, ignoredups, ignoreboth]\n"));
+       fprintf(output, _("  HISTFILE\n"
+                                         "    file name used to store the command history\n"));
+       fprintf(output, _("  HISTSIZE\n"
+                                         "    max number of commands to store in the command history\n"));
+       fprintf(output, _("  HOST\n"
+                                         "    the currently connected database server host\n"));
+       fprintf(output, _("  IGNOREEOF\n"
+                                         "    number of EOFs needed to terminate an interactive session\n"));
+       fprintf(output, _("  LASTOID\n"
+                                         "    value of the last affected OID\n"));
+       fprintf(output, _("  ON_ERROR_ROLLBACK\n"
+                                         "    if set, an error doesn't stop a transaction (uses implicit savepoints)\n"));
+       fprintf(output, _("  ON_ERROR_STOP\n"
+                                         "    stop batch execution after error\n"));
+       fprintf(output, _("  PORT\n"
+                                         "    server port of the current connection\n"));
+       fprintf(output, _("  PROMPT1\n"
+                                         "    specifies the standard psql prompt\n"));
+       fprintf(output, _("  PROMPT2\n"
+                                         "    specifies the prompt used when a statement continues from a previous line\n"));
+       fprintf(output, _("  PROMPT3\n"
+                                         "    specifies the prompt used during COPY ... FROM STDIN\n"));
+       fprintf(output, _("  QUIET\n"
+                                         "    run quietly (same as -q option)\n"));
+       fprintf(output, _("  SHOW_CONTEXT\n"
+                                         "    controls display of message context fields [never, errors, always]\n"));
+       fprintf(output, _("  SINGLELINE\n"
+                                         "    if set, end of line terminates SQL commands (same as -S option)\n"));
+       fprintf(output, _("  SINGLESTEP\n"
+                                         "    single-step mode (same as -s option)\n"));
+       fprintf(output, _("  USER\n"
+                                         "    the currently connected database user\n"));
+       fprintf(output, _("  VERBOSITY\n"
+                                         "    controls verbosity of error reports [default, verbose, terse]\n"));
 
        fprintf(output, _("\nDisplay settings:\n"));
        fprintf(output, _("Usage:\n"));
        fprintf(output, _("  psql --pset=NAME[=VALUE]\n  or \\pset NAME [VALUE] inside psql\n\n"));
 
-       fprintf(output, _("  border             border style (number)\n"));
-       fprintf(output, _("  columns            target width for the wrapped format\n"));
-       fprintf(output, _("  expanded (or x)    expanded output [on, off, auto]\n"));
-       fprintf(output, _("  fieldsep           field separator for unaligned output (default \"%s\")\n"), DEFAULT_FIELD_SEP);
-       fprintf(output, _("  fieldsep_zero      set field separator for unaligned output to zero byte\n"));
-       fprintf(output, _("  footer             enable or disable display of the table footer [on, off]\n"));
-       fprintf(output, _("  format             set output format [unaligned, aligned, wrapped, html, asciidoc, ...]\n"));
-       fprintf(output, _("  linestyle          set the border line drawing style [ascii, old-ascii, unicode]\n"));
-       fprintf(output, _("  null               set the string to be printed in place of a null value\n"));
-       fprintf(output, _("  numericlocale      enable or disable display of a locale-specific character to separate\n"
-                                         "                     groups of digits [on, off]\n"));
-       fprintf(output, _("  pager              control when an external pager is used [yes, no, always]\n"));
-       fprintf(output, _("  recordsep          record (line) separator for unaligned output\n"));
-       fprintf(output, _("  recordsep_zero     set record separator for unaligned output to zero byte\n"));
-       fprintf(output, _("  tableattr (or T)   specify attributes for table tag in html format or proportional\n"
-                                         "                     column widths for left-aligned data types in latex-longtable format\n"));
-       fprintf(output, _("  title              set the table title for any subsequently printed tables\n"));
-       fprintf(output, _("  tuples_only        if set, only actual table data is shown\n"));
+       fprintf(output, _("  border\n"
+                                         "    border style (number)\n"));
+       fprintf(output, _("  columns\n"
+                                         "    target width for the wrapped format\n"));
+       fprintf(output, _("  expanded (or x)\n"
+                                         "    expanded output [on, off, auto]\n"));
+       fprintf(output, _("  fieldsep\n"
+                                         "    field separator for unaligned output (default \"%s\")\n"),
+                       DEFAULT_FIELD_SEP);
+       fprintf(output, _("  fieldsep_zero\n"
+                                         "    set field separator for unaligned output to a zero byte\n"));
+       fprintf(output, _("  footer\n"
+                                         "    enable or disable display of the table footer [on, off]\n"));
+       fprintf(output, _("  format\n"
+                                         "    set output format [unaligned, aligned, wrapped, html, asciidoc, ...]\n"));
+       fprintf(output, _("  linestyle\n"
+                                         "    set the border line drawing style [ascii, old-ascii, unicode]\n"));
+       fprintf(output, _("  null\n"
+                                         "    set the string to be printed in place of a null value\n"));
+       fprintf(output, _("  numericlocale\n"
+                                         "    enable display of a locale-specific character to separate groups of digits\n"));
+       fprintf(output, _("  pager\n"
+                                         "    control when an external pager is used [yes, no, always]\n"));
+       fprintf(output, _("  recordsep\n"
+                                         "    record (line) separator for unaligned output\n"));
+       fprintf(output, _("  recordsep_zero\n"
+                                         "    set record separator for unaligned output to a zero byte\n"));
+       fprintf(output, _("  tableattr (or T)\n"
+                                         "    specify attributes for table tag in html format, or proportional\n"
+                                         "    column widths for left-aligned data types in latex-longtable format\n"));
+       fprintf(output, _("  title\n"
+                                         "    set the table title for subsequently printed tables\n"));
+       fprintf(output, _("  tuples_only\n"
+                                         "    if set, only actual table data is shown\n"));
        fprintf(output, _("  unicode_border_linestyle\n"
                                          "  unicode_column_linestyle\n"
                                          "  unicode_header_linestyle\n"
-                                         "                     set the style of Unicode line drawing [single, double]\n"));
+                                         "    set the style of Unicode line drawing [single, double]\n"));
 
        fprintf(output, _("\nEnvironment variables:\n"));
        fprintf(output, _("Usage:\n"));
@@ -410,23 +450,36 @@ helpVariables(unsigned short int pager)
        fprintf(output, _("  set NAME=VALUE\n  psql ...\n  or \\setenv NAME [VALUE] inside psql\n\n"));
 #endif
 
-       fprintf(output, _("  COLUMNS            number of columns for wrapped format\n"));
-       fprintf(output, _("  PAGER              name of external pager program\n"));
-       fprintf(output, _("  PGAPPNAME          same as the application_name connection parameter\n"));
-       fprintf(output, _("  PGDATABASE         same as the dbname connection parameter\n"));
-       fprintf(output, _("  PGHOST             same as the host connection parameter\n"));
-       fprintf(output, _("  PGPASSWORD         connection password (not recommended)\n"));
-       fprintf(output, _("  PGPASSFILE         password file name\n"));
-       fprintf(output, _("  PGPORT             same as the port connection parameter\n"));
-       fprintf(output, _("  PGUSER             same as the user connection parameter\n"));
+       fprintf(output, _("  COLUMNS\n"
+                                         "    number of columns for wrapped format\n"));
+       fprintf(output, _("  PAGER\n"
+                                         "    name of external pager program\n"));
+       fprintf(output, _("  PGAPPNAME\n"
+                                         "    same as the application_name connection parameter\n"));
+       fprintf(output, _("  PGDATABASE\n"
+                                         "    same as the dbname connection parameter\n"));
+       fprintf(output, _("  PGHOST\n"
+                                         "    same as the host connection parameter\n"));
+       fprintf(output, _("  PGPASSWORD\n"
+                                         "    connection password (not recommended)\n"));
+       fprintf(output, _("  PGPASSFILE\n"
+                                         "    password file name\n"));
+       fprintf(output, _("  PGPORT\n"
+                                         "    same as the port connection parameter\n"));
+       fprintf(output, _("  PGUSER\n"
+                                         "    same as the user connection parameter\n"));
        fprintf(output, _("  PSQL_EDITOR, EDITOR, VISUAL\n"
-                                         "                     editor used by the \\e, \\ef, and \\ev commands\n"));
+                                         "    editor used by the \\e, \\ef, and \\ev commands\n"));
        fprintf(output, _("  PSQL_EDITOR_LINENUMBER_ARG\n"
-                                         "                     how to specify a line number when invoking the editor\n"));
-       fprintf(output, _("  PSQL_HISTORY       alternative location for the command history file\n"));
-       fprintf(output, _("  PSQLRC             alternative location for the user's .psqlrc file\n"));
-       fprintf(output, _("  SHELL              shell used by the \\! command\n"));
-       fprintf(output, _("  TMPDIR             directory for temporary files\n"));
+                                         "    how to specify a line number when invoking the editor\n"));
+       fprintf(output, _("  PSQL_HISTORY\n"
+                                         "    alternative location for the command history file\n"));
+       fprintf(output, _("  PSQLRC\n"
+                                         "    alternative location for the user's .psqlrc file\n"));
+       fprintf(output, _("  SHELL\n"
+                                         "    shell used by the \\! command\n"));
+       fprintf(output, _("  TMPDIR\n"
+                                         "    directory for temporary files\n"));
 
        ClosePager(output);
 }