diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 95ce850195e..d9a455ba8bf 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,5 +1,5 @@ @@ -282,8 +282,8 @@ PostgreSQL documentation - Allows you to specify printing options in the style of - \pset on the command line. Note that here you + Specifies printing options, in the style of + \pset. Note that here you have to separate name and value with an equal sign instead of a space. Thus to set the output format to LaTeX, you could write -P format=latex. @@ -366,7 +366,7 @@ PostgreSQL documentation - Allows you to specify options to be placed within the + Specifies options to be placed within the HTML table tag. See \pset for details. @@ -1677,15 +1677,20 @@ lo_import 152801 - \pset parameter [ value ] + \pset option [ value ] - This command sets options affecting the output of query result - tables. parameter - describes which option is to be set. The semantics of - value depend - thereon. + This command sets options affecting the output of query result tables. + option + indicates which option is to be set. The semantics of + value vary depending + on the selected option. For some options, omitting value causes the option to be toggled + or unset, as described under the particular option. If no such + behavior is mentioned, then omitting + value just results in + the current setting being displayed. @@ -1704,27 +1709,31 @@ lo_import 152801 - Unaligned writes all columns of a row on a + unaligned format writes all columns of a row on one line, separated by the currently active field separator. This - is intended to create output that might be intended to be read - in by other programs (tab-separated, comma-separated). - Aligned mode is the standard, human-readable, + is useful for creating output that might be intended to be read + in by other programs (for example, tab-separated or comma-separated + format). + + + + aligned format is the standard, human-readable, nicely formatted text output that is default. - Wrapped is like aligned but wraps - output to the specified width. If \pset columns is - zero (the default), wrapped mode only affects screen - output and wrapped width is controlled by the environment - variable COLUMNS or the detected screen width. If - \pset columns is set to a non-zero value, all output - is wrapped, including file and pipe output. + wrapped format is like aligned but wraps + wide data values across lines to make the output fit in the target + column width. The target width is determined as described under + the columns option. Note that psql will + not attempt to wrap column header titles; therefore, + wrapped format behaves the same as aligned + if the total width needed for column headers exceeds the target. - The HTML and - LaTeX modes put out tables that are intended to + The html, latex, and troff-ms + formats put out tables that are intended to be included in documents using the respective mark-up language. They are not complete documents! (This might not be so dramatic in HTML, but in LaTeX you must @@ -1737,10 +1746,16 @@ lo_import 152801 columns - Controls the target width for the wrapped format, - and width for determining if wide output requires the pager. - Zero (the default) causes the wrapped format to - affect only screen output. + Sets the target width for the wrapped format, and also + the width limit for determining whether output is wide enough to + require the pager. + Zero (the default) causes the target width to be controlled by the + environment variable COLUMNS, or the detected screen width + if COLUMNS is not set. + In addition, if columns is zero then the + wrapped format only affects screen output. + If columns is nonzero then file and pipe output is + wrapped to that width as well. @@ -1749,12 +1764,13 @@ lo_import 152801 border - The second argument must be a number. In general, the higher + The value must be a + number. In general, the higher the number the more borders and lines the tables will have, but this depends on the particular format. In - HTML mode, this will translate directly - into the border=... attribute, in the - others only values 0 (no border), 1 (internal dividing lines), + HTML format, this will translate directly + into the border=... attribute; in the + other formats only values 0 (no border), 1 (internal dividing lines), and 2 (table frame) make sense. @@ -1769,16 +1785,18 @@ lo_import 152801 or unicode. Unique abbreviations are allowed. (That would mean one letter is enough.) + This option only affects the aligned and + wrapped output formats. ascii style uses plain ASCII characters. Newlines in data are shown using a + symbol in the right-hand margin. - When the data wraps from one line - to the next without a newline character, a dot (.) - is shown in the right-hand margin of the first line, and - again in the left-hand margin of the following line. + When the wrapped format wraps data from + one line to the next without a newline character, a dot + (.) is shown in the right-hand margin of the first line, + and again in the left-hand margin of the following line. @@ -1787,7 +1805,7 @@ lo_import 152801 in PostgreSQL 8.4 and earlier. Newlines in data are shown using a : symbol in place of the left-hand column separator. - When the data wraps from one line + When the data is wrapped from one line to the next without a newline character, a ; symbol is used in place of the left-hand column separator. @@ -1795,16 +1813,16 @@ lo_import 152801 unicode style uses Unicode box-drawing characters. Newlines in data are shown using a carriage return symbol - in the right-hand margin. When the data wraps from one line + in the right-hand margin. When the data is wrapped from one line to the next without a newline character, an ellipsis symbol is shown in the right-hand margin of the first line, and again in the left-hand margin of the following line. - When the selected output format is one that draws lines or boxes - around the data, this setting also determines the characters - with which the lines are drawn. + When the border setting is greater than zero, + this option also determines the characters + with which the border lines are drawn. Plain ASCII characters work everywhere, but Unicode characters look nicer on displays that recognize them. @@ -1821,19 +1839,16 @@ lo_import 152801 expanded (or x) - You can specify an optional second argument, if it is provided it - may be either on or off - which will enable or disable expanded mode. If the second - argument is not provided then we will toggle between regular and - expanded format. When expanded format is enabled, query results + If value is specified + it must be either on or off + which will enable or disable expanded mode. If value is omitted the command toggles + between regular and expanded mode. + When expanded mode is enabled, query results are displayed in two columns, with the column name on the left and the data on the right. This mode is useful if the data wouldn't fit on the screen in the normal horizontal mode. - - - Expanded mode is supported by all four output formats. - @@ -1841,10 +1856,9 @@ lo_import 152801 null - The second argument is a string that should be printed - whenever a column is null. The default is not to print - anything, which can easily be mistaken for, say, an empty - string. Thus, one might choose to write \pset null + Sets the string to be printed in place of a null value. + The default is to print nothing, which can easily be mistaken for + an empty string. For example, one might prefer \pset null '(null)'. @@ -1855,7 +1869,7 @@ lo_import 152801 Specifies the field separator to be used in unaligned output - mode. That way one can create, for example, tab- or + format. That way one can create, for example, tab- or comma-separated output, which other programs might prefer. To set a tab as field separator, type \pset fieldsep '\t'. The default field separator is @@ -1868,11 +1882,12 @@ lo_import 152801 footer - You can specify an optional second argument, if it is provided it - may be either on or off - which will enable or disable display of the default footer - (x rows). If the second argument is not - provided then we will toggle between on and off. + If value is specified + it must be either on or off + which will enable or disable display of the table footer + (the (n rows) count). + If value is omitted the + command toggles footer display on or off. @@ -1881,12 +1896,12 @@ lo_import 152801 numericlocale - You can specify an optional second argument, if it is provided it - may be either on or off - which will enable or disable display of a locale-aware character - to separate groups of digits to the left of the decimal marker. If - the second argument is not provided then we will toggle between - on and off. + If value is specified + it must be either on or off + which will enable or disable display of a locale-specific character + to separate groups of digits to the left of the decimal marker. + If value is omitted the + command toggles between regular and locale-specific numeric output. @@ -1896,7 +1911,7 @@ lo_import 152801 Specifies the record (line) separator to use in unaligned - output mode. The default is a newline character. + output format. The default is a newline character. @@ -1905,48 +1920,53 @@ lo_import 152801 tuples_only (or t) - You can specify an optional second argument, if it is provided it - may be either on or off - which will enable or disable the tuples only mode. If the - second argument is not provided then we will toggle between tuples - only and full display. Full display shows extra information such - as column headers, titles, and various footers. In tuples only + If value is specified + it must be either on or off + which will enable or disable tuples-only mode. + If value is omitted the + command toggles between regular and tuples-only output. + Regular output includes extra information such + as column headers, titles, and various footers. In tuples-only mode, only actual table data is shown. - title [ text ] + title Sets the table title for any subsequently printed tables. This can be used to give your output descriptive tags. If no - argument is given, the title is unset. + value is given, + the title is unset. - tableattr (or T) [ text ] + tableattr (or T) - Allows you to specify any attributes to be placed inside the - HTML table tag. This + Specifies attributes to be placed inside the + HTML table tag in + html output format. This could for example be cellpadding or bgcolor. Note that you probably don't want to specify border here, as that is already taken care of by \pset border. + If no + value is given, + the table attributes are unset. - pager - Controls use of a pager for query and psql + Controls use of a pager program for query and psql help output. If the environment variable PAGER is set, the output is piped to the specified program. Otherwise a platform-dependent default (such as @@ -1954,12 +1974,15 @@ lo_import 152801 - When the pager is off, the pager is not used. When the pager - is on, the pager is used only when appropriate, i.e. the + When the pager option is off, the pager + program is not used. When the pager option is + on, the pager is used when appropriate, i.e., when the output is to a terminal and will not fit on the screen. - \pset pager turns the pager on and off. Pager can - also be set to always, which causes the pager to be - always used. + The pager option can also be set to always, + which causes the pager to be used for all terminal output regardless + of whether it fits on the screen. \pset pager + without a value + toggles pager use on and off. @@ -1967,7 +1990,7 @@ lo_import 152801 - Illustrations on how these different formats look can be seen in + Illustrations of how these different formats look can be seen in the section. @@ -1982,8 +2005,8 @@ lo_import 152801 - It is an error to call \pset without - arguments. In the future this call might show the current status + It is an error to call \pset without any + arguments. In the future this case might show the current status of all printing options. @@ -2092,9 +2115,9 @@ lo_import 152801 \T table_options - Allows you to specify attributes to be placed within the - table tag in HTML tabular - output mode. This command is equivalent to \pset + Specifies attributes to be placed within the + table tag in HTML + output format. This command is equivalent to \pset tableattr table_options.