join(1): Add EXAMPLES section

[fernape]

Summary

Add missing EXAMPLES covering options -e, -o, -t, -v, -1. Analogous
options are not covered.

Test Plan

• mandoc -Tlint reports no errors
• aspell check --lang=en seems happy (excluding macro names an people names)
• man ./join.1 renders the page properly

[bcr]

I like the examples in general. I think they might be a bit long and couple probably be condensed a bit to still reflect the intended output. This avoids blowing up the man page with entries that are not being used. Maybe having just 3 - 5 is enough.

[fernape]

Shortening examples as suggested by bcr@

• Rerun all the EXAMPLES and checked that the match.
• mandoc -Tlint clean
• `man ./join.1' renders the page properly
• aspell seems happy

I added -e "<<NULL>>" in the last example as I think it makes things clearer.

[fernape]

Fix missing shell prompt symbol $ from last example

[bcr]

That's better, thanks!

[fernape]

In D25186#555007, @bcr wrote:

That's better, thanks!

Thanks for reviewing!

[fernape]

Since I had not committed this yet, I thought I could improve it a bit with some
of the comments/reviews received so far.

• Add .Pa to signify paths
• Use .Qq to quote a special string in the example.

[0mp]

usr.bin/join/join.1

200

As per style.mdoc(5), the use of Qq is discouraged unless there is a very good reason to use it. In this case I'd use Ql, so that it is a literal (the use of Ql is not yet documented in our style guide, which still recommends the use of Dq Li; we need to update the it because Li has been deprecated).

[fernape]

s/Qd/Ql/ as suggested by 0mp

[0mp]

Seems fine! Great job.

usr.bin/join/join.1

234

You may consider breaking this line into something that fits into 80 characters, e.g.,

$ join -t, -1 2 -o 1.2 2.2 nobel_laureates.txt nobel_nationalities.txt | \e
    sort -k2 -t, | join -t, -e "<<NULL>>" -1 2 -o 1.1 2.2 - capitals.txt