join(1) man and Info page critique

[Dan Jacobson]

The join(1) manpage talks about SIDE but never explains how to write
it.  Only on the Info page do we learn it is 1 or 2 and better called
FILE-NUMBER..

Only on the man page do we learn -j is obsolescent, not the Info page.

Only on the Info page does -a mention "in addition to the normal
output".  One has to look at -v to learn that on the man page.

Info says "In addition, when GNU `join' is invoked with exactly one
argument, options `--help' and `--version' are recognized."

Why should I know the one arg biz?  Can't I just know --help and --version?

`-a FILE-NUMBER'
     Print a line for each unpairable line in file FILE-NUMBER...

OK, but what about that line? Who would have thought that
$ join -nt, -a 2 -1 6 -2 10 file1 file2
outputs the unpairable lines of file2 with their 5th field wipped around
to the front of line! No wonder the Info page just says "a line", it
reserves artistic license for that line.

Hope you guys are having fun maintaining two versions of this information.

BTW, tac(1) man page:
       Write each FILE to standard output, last line first.
Oh, like { tail -1 file; sed 1d file;} Yeah, I know it says "reverse"
higher up on the man page, but...
-- 
http://jidanni.org/ Taiwan(04)25854780