Add missing information about the handling of input, output, and

character encoding, clarify the description of table mode, and say
that columns are filled before rows by default.
Feedback an OK jmc@, OK martijn@.

1 files changed, 33 insertions, 12 deletions

diff --git a/usr.bin/column/column.1 b/usr.bin/column/column.1
index 8666bee3b61..32ac21596b4 100644
--- a/usr.bin/column/column.1
+++ b/usr.bin/column/column.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: column.1,v 1.16 2016/03/17 07:18:34 jmc Exp $
+.\"	$OpenBSD: column.1,v 1.17 2016/10/21 07:42:17 schwarze Exp $
 .\"	$NetBSD: column.1,v 1.3 1995/03/26 09:08:28 glass Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
@@ -30,7 +30,7 @@
 .\"
 .\"     @(#)column.1	8.1 (Berkeley) 6/6/93
 .\"
-.Dd $Mdocdate: March 17 2016 $
+.Dd $Mdocdate: October 21 2016 $
 .Dt COLUMN 1
 .Os
 .Sh NAME
@@ -46,11 +46,19 @@
 The
 .Nm
 utility formats its input into multiple columns.
-Rows are filled before columns.
+Each input line provides the text for one output cell.
+Columns are filled before rows.
+.Pp
+The column width is determined by the longest input line rounded
+up to the nearest tabstop; tabstops are assumed to be at multiples
+of eight.
+Output uses tab characters to advance to the next column.
+The number of columns is chosen to fill the terminal width.
+.Pp
 Input is taken from
 .Ar file
 operands or, by default, from the standard input.
-Empty lines are ignored.
+Empty lines and lines containing only whitespace are ignored.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
@@ -59,27 +67,40 @@ Output is formatted for a display
 .Ar columns
 wide.
 .It Fl s Ar sep
-Specify a set of characters to be used to delimit columns for the
+Specify a set of characters to delimit columns for the
 .Fl t
 option.
+It defaults to space and tab.
 .It Fl t
-Determine the number of columns the input contains and create a table.
-Columns are delimited with whitespace, by default, or with the characters
-supplied using the
+Table mode.
+Each input line provides the text for one output row.
+It is split into cells using the
 .Fl s
 option.
-Useful for pretty-printing displays.
+Leading, trailing, and multiple adjacent delimiters are ignored.
+Each column is as wide as the widest cell in it.
+Columns are separated by two spaces.
 .It Fl x
-Fill columns before filling rows.
+Fill rows before filling columns.
 .El
 .Sh ENVIRONMENT
-.Bl -tag -width COLUMNS
+.Bl -tag -width LC_CTYPE
 .It Ev COLUMNS
 If set to a positive integer,
-output is formatted to the given width in (terminal) columns.
+output is formatted to the given width in display columns.
 Otherwise,
 .Nm
 defaults to the terminal width, or 80 columns if the output is not a terminal.
+.It Ev LC_CTYPE
+The character encoding
+.Xr locale 1 .
+It decides which byte sequences form characters, what their display
+width is, and which characters are whitespace.
+If unset or set to
+.Qq C ,
+.Qq POSIX ,
+or an unsupported value, each byte except the tab is treated as a
+character of display width 1.
 .El
 .Sh EXIT STATUS
 .Ex -std column