Page MenuHomeFreeBSD

join(1): Add EXAMPLES section
ClosedPublic

Authored by fernape on Jun 8 2020, 11:08 AM.

Details

Reviewers
0mp
Group Reviewers
manpages
Commits
rS362436: join(1): Add EXAMPLES section
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

Diff Detail

Repository
rS FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

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.

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.

Fix missing shell prompt symbol $ from last example

That's better, thanks!

In D25186#555007, @bcr wrote:

That's better, thanks!

Thanks for reviewing!

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 requested changes to this revision.Jun 18 2020, 6:54 PM
0mp added a subscriber: 0mp.
0mp added inline comments.
usr.bin/join/join.1
200 ↗(On Diff #73276)

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).

This revision now requires changes to proceed.Jun 18 2020, 6:54 PM

s/Qd/Ql/ as suggested by 0mp

Seems fine! Great job.

usr.bin/join/join.1
234 ↗(On Diff #73337)

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
This revision is now accepted and ready to land.Jun 19 2020, 4:39 PM
This revision was automatically updated to reflect the committed changes.