Page MenuHomeFreeBSD

iwm.4: move hardware to HARDWARE + minor cleanup
ClosedPublic

Authored by concussious.bugzilla_runbox.com on Oct 18 2024, 12:38 AM.
Referenced Files
Unknown Object (File)
Sun, Dec 1, 11:08 PM
Unknown Object (File)
Sat, Nov 30, 6:53 AM
Unknown Object (File)
Thu, Nov 28, 3:28 AM
Unknown Object (File)
Thu, Nov 21, 10:00 PM
Unknown Object (File)
Thu, Nov 21, 7:56 AM
Unknown Object (File)
Tue, Nov 19, 5:27 AM
Unknown Object (File)
Tue, Nov 19, 5:25 AM
Unknown Object (File)
Tue, Nov 19, 5:23 AM

Details

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 <gperciva@tarsnap.com> (no prompt)

If this is acceptable, please git commit --author ="Alexander Ziaee <concussious@runbox.com>" so I can demonstrate my activity. Thanks!

Test Plan

Read rendered manual page, evaluate for accuracy/consistency.

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

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

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

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

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 edited the summary of this revision. (Show Details)

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.

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

(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.

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

bz requested changes to this revision.Oct 30 2024, 1:33 AM
bz added inline comments.
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.

This revision now requires changes to proceed.Oct 30 2024, 1:33 AM

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.

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

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.

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.

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

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.

This revision was not accepted when it landed; it landed in state Needs Review.Sun, Nov 10, 7:34 PM
This revision was automatically updated to reflect the committed changes.