iwx.4: Follow the established style

[des]

Summary

Fixes: b0c1ead2b9be ("iwx.4: Fix SYNOPSIS")

[ziaee]

We have a lot of different styles in use, and I think this one is a violation of the consistency patterns in the manual as a whole. I gave a talk about it at BSDCan '25. Here's a link youtu.be/RthIOXpwwsM

[ziaee]

Pressing request changes because I gave a whole talk about how I want to get this out of the tree and have spent several months working on that.

[des]

I don't read minds and no, I'm not going to watch your talk. If you want me to change something in this patch you're going to have to tell me what, otherwise I'll commit it as-is.

[ziaee]

I want you to not change the style. This style, following the template of vt.4, is correct according to the FreeBSD documentation primer. In my talk, it was discussed that prose does not belong in synopsis according to me and mandoc upstream. This is confirmed both in mdoc(7) and Ingo's (mandoc maintainer upstream) comments on my talk. Prose in SYNOPSIS undermines the concept of SYNOPSIS, and therefore the consistency of the manual as a whole, making it more difficult to read/believe in.

[des]

Alexander, it's very simple. The manual page is currently wrong because of your commit. This patch corrects the information in the manual page and changes the style to match other similar manual pages. If you think device driver manual pages should look differently from what they do than that's your opinion and you're welcome to prepare and submit for review a mega-patch that changes them all, but until then, this change is in line with project policies.

[des]

To be absolutely clear:

% git grep -l 'To compile this driver into (the|your) kernel' freebsd/main share/man/man4 | wc -l
     353

[ziaee]

I am absolutely willing to be wrong for any technical or consensus based reason, but your appeal to force is entirely non-technical.

In D53760#1227869, @des wrote:

To be absolutely clear:

% git grep -l 'To compile this driver into (the|your) kernel' freebsd/main share/man/man4 | wc -l
     353

That is less than half of the pages in man4/.

but until then, this change is in line with project policies

What policies? I told you already that it is written according to the example in the FDP primer.

[ziaee]

To be absolutely clear, here is where it is written in the FreeBSD Documentation Project Primer:

https://docs.freebsd.org/en/books/fdp-primer/manual-pages/#manual-pages-examples-as-templates

[imp]

In D53760#1227888, @ziaee wrote:

To be absolutely clear, here is where it is written in the FreeBSD Documentation Project Primer:

https://docs.freebsd.org/en/books/fdp-primer/manual-pages/#manual-pages-examples-as-templates

Des' assertion is traditional, historical practice. It's written in what's in man4.

And the text his replaced was simply wrong.

[ziaee]

If that is your consensus you should fix the FDP primer.

[ziaee]

I gave a talk on this, so, this is actually important to me. So, this is a very bad time to use "you're wrong because you're simply wrong".

[imp]

You're right that we should update the docs. We should. At the same time, we have a lot of tribal knowledge that hasn't made it into print. And this point is what we've 'traditional' done. But that 'tradition' never was formally decided: someone, I'm not even sure anymore, did it for a few pages (since we didn't get it from 4.4BSD since it had a different syntax and no loadable kernel modules) and it was copied a lot until it became a de-facto standard and others started doing it to. It can be a bit hard to reconstruct after the fact, especially since we've had a bunch of imported from other project man pages that were imperfectly adapted.

And you're not wrong we could streamline this, since it is repetitive. But how is tricky.

The 'wrong' part of your information is that 'device wlan' won't bring this driver in. It's necessary, but not sufficient. That's why des added 'device pci' (also necessary) and 'device iwx' (which actually brings it in. His text does omit the bit about devmatch_blocklist, true, but that is documented separately in rc.conf.5 which says to use the module name, which is documented in des' text, though if we didn't have a few hundred man pages that already do this, I'd say we should consider a good way to streamline it a bit since it is a bit repetitive. Also the 'device pci' bit is squishy: many drivers, even old-time ones, don't have it. Many do. Since pci is in almost every kernel config, it often goes unnoticed as being absent.

Since you're effectively proposing an invasive change, and part of the tribal knowledge, it's traditionally discussed in one of the mailing lists first. Another bit of tribal knowledge is that you can get OK consensus on IRC and that's very often about what a mailing list discussion would bring (if you get traction: it's easier to do that on IRC). Something like this, my experience tells me, should likely be talked about in arch@, with a followup summarizing the consensus that emerges. The discussions on IRC about streamlining this are a good start at putting that proposal together. I've only seen bits an pieces of that conversation due to connectivity issues (which is why email is better for larger changes). There's also about 150 .4 man pages that document a 'driver' interface that is automatic (eg, all the dtrace ones don't need options, but the netgrraph ones due, but don't have them). So that makes looking at what the consensus is harder. I only know because I've written a few drivers, and done it both right an wrong (exca is a good example that was too minimal when I did it).

[des]

Some more numbers: there are currently 737 manual pages in share/man/man4. Of those,

• 376 have a SYNOPSIS that begins with “To compile” (353 begin with “To compile this driver”).
• 19 have a SYNOPSIS that begins with a variation on “This driver” or “The <name> driver”.
• 176 have a SYNOPSIS that begins directly with a .Bd, .Cd.
• 97 have a SYNOPSIS that begins directly with a .Fn or .In, suggesting that they don't describe a driver.
• 69 fall into neither of the above categories.

So this change brings iwx.4 in line with the prevailing style used by a solid majority of driver pages and a thin majority of section 4 pages overall.

If you want to change the prevailing style, you'll have to make a concrete proposal, build consensus for it, and actually do the work.

That FDP section is worthless, by the way. It says to use certain pages as models, but that means any change to the style of one of those pages would immediately render all the others non-compliant. If you want to mandate a specific style, you need to describe it, with concrete examples, in the documentation — after building consensus for it, of course.

[ziaee]

Okay. Thanks for the better explanations.