Page MenuHomeFreeBSD

ng manpages: Standardize descriptions
AcceptedPublic

Authored by ziaee on Sun, Sep 13, 2:15 PM.
Referenced Files
F172074567: D59643.id186780.diff
Tue, Sep 15, 11:09 PM
F172074320: D59643.id186811.diff
Tue, Sep 15, 11:07 PM
F172073565: D59643.id186810.diff
Tue, Sep 15, 10:59 PM
F172036354: D59643.diff
Tue, Sep 15, 2:55 PM
F172024301: D59643.id186601.diff
Tue, Sep 15, 11:59 AM
F171997255: D59643.id186654.diff
Tue, Sep 15, 6:09 AM
Unknown Object (File)
Mon, Sep 14, 9:37 PM
Unknown Object (File)
Mon, Sep 14, 7:56 PM
Subscribers

Details

Reviewers
dteske
glebius
des
Group Reviewers
manpages
Summary

Netgraph document descriptions are all over the place, wordsmith them
into a standard format of "%s netgraph node", trying to describe them
better.

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

ziaee requested review of this revision.Sun, Sep 13, 2:15 PM

fix mistake in ng_checksum.4

put RFC nubmers first when we have them so we don't have to use a parenthetical

expand socket in ng_socket description

improve ng_echo description

what is the difference between ng_ether and eiface?

trim l2cap, the apropos output was wraping at 80 columns

attempt to improve ng_checksum

dteske requested changes to this revision.Mon, Sep 14, 5:04 PM
dteske added a subscriber: dteske.

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

This revision now requires changes to proceed.Mon, Sep 14, 5:04 PM
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.

My only remaining suggestions

share/man/man4/ng_ether.4
40

I still think this is a good suggestion (1 of 2)

share/man/man4/ng_socket.4
41

I still think this is a good suggestion (2 of 2)

Minor nit: title s/Standarize/Standardize/ (...arize vs ...ardize)

implement @dteske's suggestions, thank you!

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)

update diff, explaination in comment

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.

ziaee retitled this revision from ng manpages: Standarize descriptions to ng manpages: Standardize descriptions.Tue, Sep 15, 8:32 PM
ziaee edited the summary of this revision. (Show Details)
ziaee added reviewers: glebius, des.
ziaee added projects: Netgraph, manpages.
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.

dteske added inline comments.
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)

This revision is now accepted and ready to land.Tue, Sep 15, 9:07 PM
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.

"ng_ip_input(4) -- IPv4 input netgraph node"?

This revision now requires review to proceed.Tue, Sep 15, 9:31 PM

"ng_ip_input(4) -- IPv4 input netgraph node"?

I like it

This revision is now accepted and ready to land.Tue, Sep 15, 11:14 PM