Page MenuHomeFreeBSD

Update the arp(4) man page to document the net.link.ether.inet.garp_rexmit_count sysctl.
ClosedPublic

Authored by dab on Oct 3 2016, 4:25 PM.

Details

Summary

Update the arp(4) man page to document the net.link.ether.inet.garp_rexmit_count sysctl.

Requested by: markj@

Test Plan

Ran igor and mandoc -Tlint; ran man and visually verified output.

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

dab retitled this revision from to Update the arp(4) man page to document the net.link.ether.inet.garp_rexmit_count sysctl..Oct 3 2016, 4:25 PM
dab updated this object.
dab edited the test plan for this revision. (Show Details)
dab added reviewers: vangyzen, markj.
dab updated this revision to Diff 20977.
dab edited the test plan for this revision. (Show Details)Oct 3 2016, 4:45 PM
dab edited edge metadata.
dab updated this object.Oct 3 2016, 5:12 PM
badger added a subscriber: badger.Oct 3 2016, 5:50 PM
badger added inline comments.
usr.sbin/arp/arp.4
141 ↗(On Diff #20977)

Seems like a space is missing between ')' and 'i'.

dab updated this revision to Diff 20984.Oct 3 2016, 6:01 PM
  • Fix typo.
markj edited edge metadata.Oct 3 2016, 6:02 PM
markj accepted this revision.

This LGTM modulo the nits. Thanks!

usr.sbin/arp/arp.4
137 ↗(On Diff #20977)

This convention of writing numbers isn't present elsewhere in this file - I'd just write "0".

141 ↗(On Diff #20977)

Missing space after the close paren.

This revision is now accepted and ready to land.Oct 3 2016, 6:02 PM
dab edited edge metadata.Oct 3 2016, 6:03 PM
dab updated this revision to Diff 20985.
  • Leave out parenthetical numbers (e.g., "zero (0)").
This revision now requires review to proceed.Oct 3 2016, 6:03 PM
dab added a comment.Oct 3 2016, 6:03 PM

Thanks, @markj; fixed.

dab marked 3 inline comments as done.Oct 3 2016, 6:44 PM
vangyzen edited edge metadata.Oct 3 2016, 6:52 PM
vangyzen accepted this revision.
This revision is now accepted and ready to land.Oct 3 2016, 6:52 PM
This revision was automatically updated to reflect the committed changes.
wblock added a subscriber: wblock.Oct 7 2016, 3:23 PM
wblock added inline comments.
head/usr.sbin/arp/arp.4
130

I suspect this is an ambiguous wording even for native English speakers, the leading "should" makes it sound like a question. How about:
Whether the kernel should

141

The "although" kind of fights with the later parts of the sentence, and the whole sentence is kind of long. How about:

The default behavior of a single GARP packet is usually sufficient.
However, in circumstances like when a shared address is passed between cluster
nodes, this single GARP might be dropped or lost.

(Note also the change from "may", usually implying "you are allowed", to "might", meaning "potentially".)

146

As above, s/may/might/.

148

Ah, these were in the original. They still are not good for clarity, but makes it clearer why the new sections were worded that way.

149

This is a typo (not yours, just pointing it out): s/an other/another/.

dab added inline comments.Oct 7 2016, 4:24 PM
head/usr.sbin/arp/arp.4
130

As you later noted, this phrasing is used in the existing descriptions, so I attempted to match it. I agree it is odd. Would you prefer I change this (new) description only, leave as-is, or modify all the descriptions to avoid the odd phrasing?

141

Good suggestion, although my inner grammarian prefers "such as" to "like".

vangyzen added inline comments.Oct 7 2016, 4:40 PM
head/usr.sbin/arp/arp.4
130

If you modify this one, please make them all consistent.

Removing everything before "retransmit" would be clear and succinct.

141

I like @wblock's suggestion, too. Now that I'm reading it again, however, the meaning is actually not quite right. The GARP can be dropped or lost in any case; it's just more harmful in the mentioned case.

wblock added inline comments.Oct 7 2016, 4:58 PM
head/usr.sbin/arp/arp.4
130

My preference would be to fix them all, but I didn't mean to expand this with mission creep. If you want to do that, it's fine. If not, please let me know, and I will do it.

141

"such as when" sounds more wrong than "like when" to me, but that might be a regional thing. This might be best cleared up by splitting the two thoughts into two sentences. The first is that sometimes the GARP might be dropped or lost, the second is examples of a typical cause of that. Maybe @vangyzen's point can be worked into that:

The default behavior of a single GARP packet is usually sufficient.
However, a single GARP might be dropped or lost in some circumstances.
This is particularly harmful when a shared address is being passed between cluster nodes.
vangyzen added inline comments.Oct 7 2016, 5:21 PM
head/usr.sbin/arp/arp.4
130

I told him the same thing offline. :)

141

Nice wording, @wblock.

dab added a comment.Oct 7 2016, 6:11 PM

Further comments and follow-up on the arp(4) man page are directed to D8183.