X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=text-utils%2Fcolumn.1;h=e43d6fee406ec63ad969d304eba0963d0cafe2b7;hb=67e63c12635f0edc7600c4fd1ab44e03ae9552f1;hp=3bcd0f086e59cc16cf954e3e0245d9674f09dc2a;hpb=785e5436458abe220f08c086a13f333f093b2167;p=thirdparty%2Futil-linux.git diff --git a/text-utils/column.1 b/text-utils/column.1 index 3bcd0f086e..e43d6fee40 100644 --- a/text-utils/column.1 +++ b/text-utils/column.1 @@ -31,7 +31,7 @@ .\" .\" @(#)column.1 8.1 (Berkeley) 6/6/93 .\" -.TH COLUMN 1 "January 2017" "util-linux" "User Commands" +.TH COLUMN 1 "February 2019" "util-linux" "User Commands" .SH NAME column \- columnate lists .SH SYNOPSIS @@ -42,19 +42,19 @@ The .B column utility formats its input into multiple columns. The util support three modes: .TP -.BR "columns are filled before rows" +.B columns are filled before rows This is the default mode (required by backward compatibility). .TP -.BR "rows are filed before columns" -This mode is enabled by option \fB-x, \-\-fillrows\fP +.B rows are filled before columns +This mode is enabled by option \fB\-x, \-\-fillrows\fP .TP -.BR "table" +.B table Determine the number of columns the input contains and create a table. This -mode is enabled by option \fB-t, \-\-table\fP and columns formatting is +mode is enabled by option \fB\-t, \-\-table\fP and columns formatting is possible to modify by \fB\-\-table-*\fP options. Use this mode if not sure. .PP Input is taken from \fIfile\fR, or otherwise from standard input. Empty lines -are ignored. +are ignored and all invalid multibyte sequences are encoded by \\x convention. .PP .SH OPTIONS The argument \fIcolumns\fP for \fB\-\-table-*\fP options is comma separated @@ -66,7 +66,7 @@ Use JSON output format to print the table, the option \fB\-\-table\-columns\fP is required and the option \fB\-\-table\-name\fP is recommended. .IP "\fB\-c, \-\-output\-width\fP \fIwidth\fP" Output is formatted to a width specified as number of characters. The original -name of this option is --columns; this name is deprecated since v2.30. Note that input +name of this option is \-\-columns; this name is deprecated since v2.30. Note that input longer than \fIwidth\fP is not truncated by default. .IP "\fB\-d, \-\-table\-noheadings\fP" Do not print header. This option allows to use logical column names on command line, but keep the header hidden when print the table. @@ -81,7 +81,7 @@ supplied using the \fB\-\-output\-separator\fP option. Table output is useful for pretty-printing. .IP "\fB\-N, \-\-table-columns\fP \fInames\fP" Specify the columns names by comma separated list of names. The names are used -for the table header or to addres column in option arguments. +for the table header or to address column in option arguments. .IP "\fB\-R, \-\-table-right\fP \fIcolumns\fP" Right align text in the specified columns. .IP "\fB\-T, \-\-table-truncate\fP \fIcolumns\fP" @@ -100,11 +100,15 @@ Print header line for each page. Specify columns where is possible to use multi-line cell for long text when necessary. .IP "\fB\-H, \-\-table-hide\fP \fIcolumns\fP" -Don't print specified columns. +Don't print specified columns. The special placeholder '\-' may be used to +hide all unnamed columns (see \-\-table-columns). .IP "\fB\-O, \-\-table-order\fP \fIcolumns\fP" Specify columns order on output. .IP "\fB\-n, \-\-table-name\fP \fIname\fP" -Specify the table name used for JSON output. The defaout is "table". +Specify the table name used for JSON output. The default is "table". +.IP "\fB\-L, \-\-table\-empty\-lines\fP" +Insert empty line to the table for each empty line on input. The default +is ignore empty lines at all. .IP "\fB\-r, \-\-tree\fP \fIcolumn\fP" Specify column to use tree-like output. Note that the circular dependencies and another anomalies in child and parent relation are silently ignored. @@ -122,28 +126,15 @@ Display help text and exit. .SH ENVIRONMENT The environment variable \fBCOLUMNS\fR is used to determine the size of the screen if no other information is available. -.SH EXAMPLES -Print fstab with header line and align number to the right: -.EX -\fBsed 's/#.*//' /etc/fstab | column --table --table-columns SOURCE,TARGET,TYPE,OPTIONS,PASS,FREQ --table-right PASS,FREQ\fR -.EE -.PP -Print a tree: -.EX -\fBecho -e '1 0 A\\n2 1 AA\\n3 1 AB\\n4 2 AAA\\n5 2 AAB' | column --tree-id 1 --tree-parent 2 --tree 3\fR -1 0 A -2 1 |-AA -4 2 | |-AAA -5 2 | `-AAB -3 1 `-AB -.EE +.SH HISTORY +The column command appeared in 4.3BSD-Reno. .SH BUGS Version 2.23 changed the .B \-s option to be non-greedy, for example: .PP .EX -\fBprintf "a:b:c\\n1::3\\n" | column -t -s ':'\fR +\fBprintf "a:b:c\\n1::3\\n" | column \-t \-s ':'\fR .EE .PP Old output: @@ -157,13 +148,42 @@ New output (since util-linux 2.23): a b c 1 3 .EE -.SH "SEE ALSO" +.PP +Historical versions of this tool indicated that "rows are filled before +columns" by default, and that the +.B \-x +option reverses this. This wording did not reflect the actual behavior, and it +has since been corrected (see above). Other implementations of +.B column +may continue to use the older documentation, but the behavior should be +identical in any case. +.SH EXAMPLE +Print fstab with header line and align number to the right: +.EX +\fBsed 's/#.*//' /etc/fstab | column \-\-table \-\-table-columns SOURCE,TARGET,TYPE,OPTIONS,PASS,FREQ \-\-table-right PASS,FREQ\fR +.EE +.PP +Print fstab and hide unnamed columns: +.EX +\fBsed 's/#.*//' /etc/fstab | column \-\-table \-\-table-columns SOURCE,TARGET,TYPE \-\-table-hide \-\fR +.EE +.PP + +.PP +Print a tree: +.EX +\fBecho \-e '1 0 A\\n2 1 AA\\n3 1 AB\\n4 2 AAA\\n5 2 AAB' | column \-\-tree-id 1 \-\-tree-parent 2 \-\-tree 3\fR +1 0 A +2 1 |-AA +4 2 | |-AAA +5 2 | `-AAB +3 1 `-AB +.EE +.SH SEE ALSO .BR colrm (1), .BR ls (1), .BR paste (1), .BR sort (1) -.SH HISTORY -The column command appeared in 4.3BSD-Reno. .SH AVAILABILITY The column command is part of the util-linux package and is available from https://www.kernel.org/pub/linux/utils/util-linux/.