Netgraph document descriptions are all over the place, wordsmith them
into a standard format of "%s netgraph node", trying to describe them
better.
Details
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
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. | |
| share/man/man4/ng_socket.4 | ||
|---|---|---|
| 41 | Original was "netgraph socket node type" Much of the other changes were to just remove "type" That's what I'm advocating here, but somehow we ended up growing a second "netgraph" (netgraph socket netgraph node) | |
| share/man/man4/ng_btsocket.4 | ||
|---|---|---|
| 32 | I put this in plural since this IIUC there are multiple? This probably can/should be improved further. | |
| share/man/man4/ng_ip_input.4 | ||
| 67 | what does IP stand for here? we should spell this out. | |
| share/man/man4/ng_socket.4 | ||
| 41 | Ok, yeah... What about this, I changed it to: ng_socket(4) - socket interface netgraph node and ng_device(4) - device interface netgraph node Also in this update, Gleb explained to me a little more about ng_UI, so I changed that to: ng_UI(4) - HDLC UI header stripping/prepending netgraph node and also capitalized the PPP expansion. | |
| share/man/man4/ng_btsocket.4 | ||
|---|---|---|
| 32 | Yes, that's correct. I caught the plurality and accepted it as correct previously (by not commenting on it) but will explicitly comment that it is correct. | |
| share/man/man4/ng_ip_input.4 | ||
|---|---|---|
| 67 | IP is Internet Protocol and because the KLD is ng_ip_input we could absolutely expand it if you like. Not sure if you were being sarcastic. I suspect sarcasm, because we also have below IP Firewall which could become Internet Protocol Firewall if you wanted (but I think we're bordering on something) | |
| share/man/man4/ng_ip_input.4 | ||
|---|---|---|
| 67 | No actually! The manpage says "queues them into the IP in input processing subsystem."... so like... it wouldn't make sense to be internet protocol based on that grammar, so... maybe... there's 3 IPs! IP in the Nd, IP in the input processing subsystem, and IP (input processing) subsystem. | |