Bug 235946 - column(1): Fill order (with/without -x) is incorrectly documented
Summary: column(1): Fill order (with/without -x) is incorrectly documented
Status: New
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: freebsd-bugs (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2019-02-22 22:03 UTC by dana
Modified: 2019-02-22 22:03 UTC (History)
1 user (show)

See Also:


Attachments
column(1) documentation fix (1.19 KB, patch)
2019-02-22 22:03 UTC, dana
no flags Details | Diff
column(1) source comment (523 bytes, patch)
2019-02-22 22:03 UTC, dana
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description dana 2019-02-22 22:03:07 UTC
Created attachment 202276 [details]
column(1) documentation fix

The documentation for column(1) says that 'Rows are filled before columns' and that the -x option 'Fill[s] columns before filling rows'. The language dates back to at least 4.4BSD, and it matches the names of the functions responsible for the corresponding output modes in the source code. However, i don't think that most people would interpret that wording the way the original developers apparently did:

% printf '%s\n' aaa bbb ccc ddd eee | column -c24
aaa     ccc     eee
bbb     ddd
% printf '%s\n' aaa bbb ccc ddd eee | column -xc24
aaa     bbb     ccc
ddd     eee

To me, the default behaviour is clearly filling the columns first, whilst the -x behaviour is filling the rows first.

The developers of the util-linux[1] and OpenBSD[2] implementations of column(1) evidently agree, since their man pages now state that the default behaviour is to fill columns first.

I've attached a patch that changes the man page to bring it in line with util-linux and OpenBSD.

When util-linux fixed their documentation, they also updated the source code to match. OpenBSD did not, maybe because simply swapping the function names would make it very confusing to compare the source to other/historical BSDs. I've gone the OpenBSD route here, but i did add a comment about it.

PS: Sorry if i've misunderstood anything; this is my first time submitting a bug/patch to FreeBSD directly.

[1] https://github.com/karelzak/util-linux/blob/2698f9ba887cb7e4a204ada72016b1c1192b17c1/text-utils/column.1

[2] https://github.com/openbsd/src/blob/c37de4bcf15ea51b5fae88c6b1911bf615329586/usr.bin/column/column.1
Comment 1 dana 2019-02-22 22:03:44 UTC
Created attachment 202277 [details]
column(1) source comment