[Bug 235946] column(1): Fill order (with/without -x) is incorrectly documented

[bugzilla-noreply at freebsd.org]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=235946

            Bug ID: 235946
           Summary: column(1): Fill order (with/without -x) is incorrectly
                    documented
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Only Me
          Priority: ---
         Component: Manual Pages
          Assignee: bugs at FreeBSD.org
          Reporter: dana at dana.is
                CC: doc at FreeBSD.org

Created attachment 202276
  --> https://bugs.freebsd.org/bugzilla/attachment.cgi?id=202276&action=edit
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

-- 
You are receiving this mail because:
You are on the CC list for the bug.