OUTSTANDING: description of ng_UI is guess.
Event: EuroBSDcon 2026
Discussed with: des, glebius
MFC after: 3 days
Details
Details
Diff Detail
Diff Detail
- Repository
- rG FreeBSD src repository
- Lint
Lint Skipped - Unit
Tests Skipped - Build Status
Buildable 76877 Build 73760: arc lint + arc unit
Event Timeline
Comment Actions
Good work, but there needs to be consistency, and I feel like selectively expanding some acronyms unnecessarily worsens the topological search scape, and there is at least one description that is wrong (ng_socket)
| share/man/man4/ng_ether.4 | ||
|---|---|---|
| 40 | to clear up the confusion between what makes ng_ether and ng_eiface different | |
| share/man/man4/ng_hci.4 | ||
| 32 | I'm on the fence on this one. I'd prefer the acronym to stay aligned with other places where we prefer the acryonym, such as HDLC. People looking for HCI won't spell it out, just as people looking for HDLC support won't be searching for High-Level Data Link Control | |
| share/man/man4/ng_l2tp.4 | ||
| 43 | Like HDLC and L2CAP (and proposed HCI change) I suggest keeping to L2TP here (and removing "protocol" which was redundant as the P in L2TP is already protocol) | |
| share/man/man4/ng_lmi.4 | ||
| 41 | Like HDLC, L2CAP, HCI, L2TP, the acronym LMI is what frame relay people will be searching for, and those curious about frame relay will look up LMI and then understand that it is an industry standard acronym that has meaning in the frame relay community. | |
| share/man/man4/ng_nat.4 | ||
| 30 | I'll give you this one, but can we at least capitalize? | |
| share/man/man4/ng_ppp.4 | ||
| 41 | PPP programmers will be searching for PPP not point to point (which if you wanted to use, would be hyphenated as point-to-point). Suggest going back to PPP here though, but if you really don't like that, the correct thing to put would in-fact be "point-to-point" | |
| share/man/man4/ng_pppoe.4 | ||
| 41 | Please, God, No. We have PPPoE for a reason. People know what PPPoE is. I mean, if you're going to expand every acronym to make a historical dictionary of technical jargon, people won't be able to find what they need because not everybody knows what acronyms stand for (and thusly, we'd land ourselves back into needing parentheticals just so people could find what they need). | |
| share/man/man4/ng_rfc1490.4 | ||
| 41 | Like ng_pred1 why can't we have both the RFC and the definition in one descriptor? | |
| share/man/man4/ng_socket.4 | ||
| 41 | The use of "Berkeley" here is wrong. ng_socket is used by ngctl to connect to the netgraph system to communicate with netgraph itself. Calling it a Berkeley socket may be accurate but it doesn't strike at the purpose and duty that it performs. | |
| share/man/man4/ng_tcpmss.4 | ||
| 30 | To TCP programmers, MSS is rarely if-ever spelled-out | |
| share/man/man4/ng_hci.4 | ||
|---|---|---|
| 32 | I retract my suggestion here because HCI is in the KLD name (ng_hci) and you convinced me that if we have space the expansion is erudite | |
| share/man/man4/ng_l2tp.4 | ||
| 43 | I retract this suggestion too, again because KLD name (ng_lt2p) has the acronym, and so the expansion is luciferous | |
| share/man/man4/ng_lmi.4 | ||
| 41 | My objection to expansion here is released as well, again because the KLD (ng_lmi) gives us context to the expanded prose | |
| share/man/man4/ng_nat.4 | ||
| 30 | I am ambivalent here on the capitalization (one might argue that because we don't pedantically capitalize the other expansions, we should do without it here) | |
| share/man/man4/ng_ppp.4 | ||
| 41 | You educated me on IRC that apropos searches both Nm and Nd, and clearly we have ppp in the KLD name, expand away | |
| share/man/man4/ng_pppoe.4 | ||
| 41 | I was a bit dramatic here (non-maliciously, was supposed to be tongue-in-cheek, though it has been over 20 years since I have seen PPPoE expanded). That being said, as is the case with the other prior objections, we've got the acronym in the KLD and so the expansion is illuminating. After all, you are right, having the expansion here against the KLD name could even make people WANT to read these man-pages (as a form of education on networking standards with the expanded meanings front-and-center). Go forth and expand | |
| share/man/man4/ng_rfc1490.4 | ||
| 41 | Duh, I wasn't looking at the KLD name, putting the RFC in the Nd here would be entirely redundant. | |
| share/man/man4/ng_socket.4 | ||
| 41 | Ok to lower-case Netgraph to illicit netgraph(4) reference | |
| share/man/man4/ng_tcpmss.4 | ||
| 30 | Except I was completely not looking at Nm, apologies. Derp. | |