From c833a76d4e58a0eb88ff3e301c33abd3bb8b7c0e Mon Sep 17 00:00:00 2001
From: Ingo Schwarze <schwarze@cvs.openbsd.org>
Date: Fri, 21 Oct 2016 07:42:18 +0000
Subject: 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@.

---
 usr.bin/column/column.1 | 45 +++++++++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 12 deletions(-)

(limited to 'usr.bin/column')

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
-- 
cgit v1.2.3