Please consider including this patch to add examples to the join
manpage.

diff -Naur coreutils-5.97.orig/man/join.x coreutils-5.97/man/join.x
--- coreutils-5.97.orig/man/join.x	1999-11-02 08:58:56.000000000 -0500
+++ coreutils-5.97/man/join.x	2007-09-13 20:18:18.000000000 -0400
@@ -2 +2,20 @@
 join \- join lines of two files on a common field
+[EXAMPLES]
+.TP
+List lines from file1 not in file2. \
+  file1 is joined on the 9th field and file2 is joined on the 6th.
+.nf
+.B sort -k 9 ./file1.in >./file1
+.B sort -k 6 ./file2.in >./file2
+.B join -v 1 -1 9 -2 6 ./file1 ./file2
+.fi
+.TP
+List pathnames in the join field in file2 but not in file1. \
+Sort by filesize from the 3rd field of the file2. \
+Output is followed by by the filesize from the 5th field of file1, then the common pathname.
+.B join -o '2.3 1.5 0' -v 2 -1 9 -2 6 ./file1 ./file2 |sort -nr
+.TP
+List pathnames common to both files, \
+again sorting by filesize from file2.
+.B join -o '2.3 1.5 0' -1 9 -2 6 ./file1 ./file2 |sort -nr
+.LP

Updated patch; s/ by by / by /

diff -Naur coreutils-5.97.orig/man/join.x coreutils-5.97/man/join.x
--- coreutils-5.97.orig/man/join.x	1999-11-02 08:58:56.000000000 -0500
+++ coreutils-5.97/man/join.x	2007-09-13 20:18:18.000000000 -0400
@@ -2 +2,20 @@
 join \- join lines of two files on a common field
+[EXAMPLES]
+.TP
+List lines from file1 not in file2. \
+  file1 is joined on the 9th field and file2 is joined on the 6th.
+.nf
+.B sort -k 9 ./file1.in >./file1
+.B sort -k 6 ./file2.in >./file2
+.B join -v 1 -1 9 -2 6 ./file1 ./file2
+.fi
+.TP
+List pathnames in the join field in file2 but not in file1. \
+Sort by filesize from the 3rd field of the file2. \
+Output is followed by the filesize from the 5th field of file1, then the common pathname.
+.B join -o '2.3 1.5 0' -v 2 -1 9 -2 6 ./file1 ./file2 |sort -nr
+.TP
+List pathnames common to both files, \
+again sorting by filesize from file2.
+.B join -o '2.3 1.5 0' -1 9 -2 6 ./file1 ./file2 |sort -nr
+.LP

Follow-up to
http://bugs.debian.org/442196
(coreutils: please include join manpage example)

Hi Justin,

There's actually an example already in the Texinfo manual (info join).
I'm not against having some example in the man page too, but yours
doesn't seem to illustrate very well what join does (what is the content
of file1.in and file2.in, what is the output of each command, etc.)

What do you think about the example in the Texinfo manual? Do you think
it should go in the man page? Would you be willing to rework your patch
to include more details about the input and output?

Cheers,