Details

Reviewers

adrian
ziaee

Group Reviewers

manpages
network

Commits

rGc21c8a10d739: IfAPI: Update ifnet(9) man page

Summary

Extremely rough start of documenting the IfAPI.

Posting to solicit feedback on if this is the right way to do it, my man-fu
is... bad at best.

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

jhibbits created this revision.Dec 5 2024, 4:11 PM

Herald added a subscriber: imp. · View Herald TranscriptDec 5 2024, 4:11 PM

jhibbits requested review of this revision.Dec 5 2024, 4:11 PM

Harbormaster completed remote builds in B60968: Diff 147531.Dec 5 2024, 4:11 PM

emaste added a subscriber: emaste.Dec 5 2024, 4:56 PM

emaste added inline comments.

share/man/man9/Makefile
1377	I wonder if we should mlink it or have a standalone ifapi(9) (as we do with iflib)? Not sure, but if we do decide to do so it could be a subsequent change.
share/man/man9/ifnet.9
104	blank lines are discouraged in man pages I believe, use `.\"` if spacing is desired for readability

This is cool! Just a few tiny nits from me. emaste is correct about the empty space, it actually produces two linter errors.

share/man/man9/ifnet.9
29	You wanna spell out the whole month in mdoc(7) or it produces a linter error. You can check the linter for errors with `mandoc -Tlint share/man/man9/ifnet.9`.
424–425	Not sure if this is correct, but there are a striking amount of parenthesis here, making it hard to understand.
434–435
439–441	Again, not sure that this meaning is correct, you may need to use a different word than "attaching" but lots of parenthesis is stressful for English.
444–451	Although, style.mdoc(5) says `Dq Li` is deprecated and suggests using `Ql` instead. Note that this renders as single quoted instead of double quoted.
465
478	You may need to use different word than "attaching", I do not understand the code, but full sentences inside parenthesis, particularly with punctuation, is kinda... a grammatical structure of last resort in American English.
492
517–518
527–528
532–533
538–540
544
546
557

Address feedback. Also ran mandoc -T lint over it, and fixed existing lint errors.

Harbormaster completed remote builds in B61068: Diff 147777.Dec 10 2024, 5:04 PM

Update date.

Harbormaster completed remote builds in B61069: Diff 147778.Dec 10 2024, 5:05 PM

In D47931#1092874, @concussious.bugzilla_runbox.com wrote:

This is cool! Just a few tiny nits from me. emaste is correct about the empty space, it actually produces two linter errors.

Thanks for the review. Some of the nits you pointed out were preexisting, where I simply moved the text around, but I'm glad you pointed the issues out, so I can correct them to better fit with the function APIs rather than the preexisting structure.

I think I've fixed everything you pointed out.

Actually update the date...

Harbormaster completed remote builds in B61077: Diff 147793.Dec 10 2024, 8:16 PM

Ping? Been a couple months, want to wrap it all up.

i think it's fine, I think it's ok to land it and then iterate some more if people have other feedback.

thanks for tackling this!

This revision is now accepted and ready to land.Fri, Feb 28, 8:27 PM

ziaee added inline comments.Fri, Feb 28, 8:33 PM

share/man/man9/Makefile
1377	Is it supposed to have a slash if it's just one line?
share/man/man9/ifnet.9
405–406	Since these options are too long to indent over, style.mdoc(5) says we should set the width to indent.

jhibbits added inline comments.Fri, Feb 28, 8:38 PM

share/man/man9/Makefile
1377	At Juniper the common practice is to add a backslash and blank line "just in case", but I'll remove it.
share/man/man9/ifnet.9
405–406	Sorry, I know absolutely nothing about mdoc, can you give an example of setting the width, and what would be appropriate here?