iwm.4: move hardware to HARDWARE + minor cleanup

[concussious.bugzilla_runbox.com]

Summary

iwm.4: move hardware to HARDWARE + minor cleanup

Add devices supported by this driver to a HARDWARE section
for inclusion in the release Hardware Compatibility Notes.

While here:
+ license: add spdx license identifier tag
+ synopsis: join a line for grep/brevity
+ description: reflow for consistency, xref iwmfw(4)
+ examples: use test-net-1 in cidr(!) as example ip4 address
+ see also: add networking(7) quick start guide
+ bugs: move 'incompatible modes' here for consistency/flow
+ mention 802.11a support

MFC after:      3 days
Reported by:      bz (relnotes generation, cidr, test-net-1 ip4addr)
Reported by:     Graham Percival <[e-mail]> (no prompt)

If this is acceptable, please git commit --author ="Alexander Ziaee <[e-mail]>" so I can demonstrate my activity. Thanks!

Test Plan

Read rendered manual page, evaluate for accuracy/consistency.

[concussious.bugzilla_runbox.com]

+ description: move 'for more info' to section bottom
+ examples: use the ip4 address reserved for documentation, test-net-1

[concussious.bugzilla_runbox.com]

+ fix typo, reflow description, use iv4 documentation address for example

[concussious.bugzilla_runbox.com]

improve introduction

[bz]

I wonder if we want to add a note forward to iwlwifi(4). @emaste I seem to remember you having a review open to switch defaults. Do we want to leave a note here at least that all these devices are equally supported by iwlwifi(4)?

share/man/man4/iwm.4

126

192.0.2.20/24 (and we can ditch the netmask line). 192.0.2.0 is the network address.

191

I would say a/b/g as it does support a

[concussious.bugzilla_runbox.com]

192.0.2.20/24 (and we can ditch the netmask line). 192.0.2.0 is the network address.

Awesome, thank you!

[concussious.bugzilla_runbox.com]

mention 802.11a, and convert example to cidr notation! Thank you so much, many people in the community have wanted this for a long time. I'll do the rest of them in one review.

[concussious.bugzilla_runbox.com]

Correct my backwards forward slash, thank you for your patience.

[gperciva_tarsnap.com]

(Sorry, I forgot to click "submit" when I looked at this a few days ago.

share/man/man4/iwm.4

131

I don't think that all the # helps things, and it makes it harder to copy&paste commands.

(without a #, in my terminal I can triple-click to copy the entire line; when it's there, I need to move the cursor after the # and drag it across)

I know that you want to make it clear that this is a root command, but I think that's clear from the context. Also, none (or very few) other man-pages include $ or # chars to indicate whether it's for normal users or root.

[concussious.bugzilla_runbox.com]

Okay, thanks Graham! That sounds good. Next push will revert proposed example prompts.

[bz]

share/man/man4/iwm.4

101

Are we going to revert these too like https://github.com/freebsd/freebsd-src/pull/1462 does?

I still wonder if that was something of the old script for the website (I should go and dig it up), which liked to parse things this way.

[concussious.bugzilla_runbox.com]

I'd like to make it consistent if possible. The patch on github switches from Bl to Bd so that the extra spaces used for alignment will render.

[concussious.bugzilla_runbox.com]

+ s/Nm iwmfw/Xr iwmfw 4/
+ adjust HARDWARE to proposed display block convention

[bz]

I'll leave the comment here (applies to github as well I would assume):

Looking at https://www.freebsd.org/releases/14.2R/hardware/ we have 4 different styles (at least 3 in "WiFi").
<pre> tables with multi-column; <li> dot lists; un-whatever lists. And then there's single line plain comma separated lists in other sections.

Out of these the <li> * Foo sections seem to look nicest, and also provide a coherent sub-section.
After that the <pre>-formated tables render acceptable but seem to have more information than required for this document.

In other words, I'd prefer the way iwlwifi got rendered over the way rtw88 got rendered.

What the difference in term of correct mandoc is I cannot say.

[concussious.bugzilla_runbox.com]

In other words, I'd prefer the way iwlwifi got rendered over the way rtw88 got rendered.

That's a big help. Now that they're expanded, we can see them. That's how I'll do it for the rest of them then, the coherent subsections are clearly much more important than aligning things.

As far as correct, I think this is up to us. I've read all the style guides I could find, this is not mentioned.

[concussious.bugzilla_runbox.com]

Use a bullet list for hardware
While here improve some language and fold pesky lines.

[bz]

share/man/man4/iwm.4

84

this is actually not fully correct I believe but probably good enough. I believe it does not support all of them. We should probably say "most".
I'll add the word before committing.