Re: git: 4262dbc57982 - main - wifi manuals: Mlink + document description consistency
Date: Fri, 07 Mar 2025 20:19:36 UTC
On Thu, 6 Mar 2025, Alexander Ziaee wrote: > On 2025-03-04 12:07 -05:00 EST, "Warner Losh" <imp@bsdimp.com> wrote: >> On Tue, Mar 4, 2025 at 8:23 AM John Baldwin <jhb@freebsd.org> wrote: >> >>> On 3/4/25 09:25, Bjoern A. Zeeb wrote: >>>> On Tue, 4 Mar 2025, Herbert J. Skuhra wrote: >>>> >>>>> On Thu, 27 Feb 2025 23:22:00 +0100, Alexander Ziaee wrote: >>>>>> >>>>>> The branch main has been updated by ziaee: >>>>>> >>>>>> URL: >>> https://cgit.FreeBSD.org/src/commit/?id=4262dbc57982383eb61a8b7806de6dd4b7802da8 >>>>>> >>>>>> commit 4262dbc57982383eb61a8b7806de6dd4b7802da8 >>>>>> Author: Alexander Ziaee <ziaee@FreeBSD.org> >>>>>> AuthorDate: 2025-02-19 15:54:27 +0000 >>>>>> Commit: Alexander Ziaee <ziaee@FreeBSD.org> >>>>>> CommitDate: 2025-02-27 22:20:22 +0000 >>>>>> >>>>>> wifi manuals: Mlink + document description consistency >>>>>> >>>>>> Interfaces all have an mlink to if_$foo. Add these for the >>> missing ones >>>>>> and remove an incorrect one from rtwn_pci. Wireless network >>> drivers are >>>>>> all accessible via `apropos -s4 "wireless network driver", except >>> two >>>>>> which are "wireless network device". I actually prefer the >>> latter, but >>>>>> make them all consistent upon the more common parlance. Tag SPDX >>> on one >>>>>> of the files I touched, while here. >>>>>> >>>>>> MFC after: 3 days >>>>>> Reviewed by: bz, carlavilla, mhorne >>>>>> Approved by: carlavilla, mhorne (mentors) >>>>>> Differential Revision: https://reviews.freebsd.org/D49063 >>>>>> --- >>>>>> share/man/man4/Makefile | 4 +++- >>>>>> share/man/man4/uath.4 | 4 +++- >>>>>> share/man/man4/upgt.4 | 2 +- >>>>>> 3 files changed, 7 insertions(+), 3 deletions(-) >>>>>> >>>>>> diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile >>>>>> index 13afc9b8d399..8e0af19eec3d 100644 >>>>>> --- a/share/man/man4/Makefile >>>>>> +++ b/share/man/man4/Makefile >>>>>> @@ -764,7 +764,9 @@ MLINKS+=ptnet.4 if_ptnet.4 >>>>>> MLINKS+=ral.4 if_ral.4 >>>>>> MLINKS+=re.4 if_re.4 >>>>>> MLINKS+=rl.4 if_rl.4 >>>>>> -MLINKS+=rtwn_pci.4 if_rtwn_pci.4 >>>>>> +MLINKS+=rtw88.4 if_rtw89.4 >>>>>> +MLINKS+=rtw89.4 if_rtw89.4 >>>>>> +MLINKS+=rtwn.4 if_rtwn.4 >>>>> ^^^^^^^^^ >>>>> $ grep if_rtwn.4 ObsoleteFiles.inc >>>>> OLD_FILES+=usr/share/man/man4/if_rtwn.4.gz >>>> >>>> In fact that is probably correct but things are confusing. >>>> >>>> The modules are called if_rtwn_usb.ko and if_rtwn_pci.ko and those >>>> should have the man page and links (so contrary to what was done). >>>> rtwn.ko is just the common code if I am not mistaken (Adrian should know >>>> better). >>>> >>>> But everyone is just referring to the driver as rtwn and I fear if there >>>> is no man page to be found as man rtwn / man if_rtwn people will be >>>> confused. >>>> >>>> I wanted to do the same with rtw88 but was told to keep it all together >>>> as one so rtwn is an excemption. >>>> >>>> That all said, yes, it needs a further cleanup. >>> >>> The manpages should just be rtwn/if_rtwn. The bus attachment doesn't >>> matter. >>> We don't have separate manpages when a storage adapter has been supported >>> on both PCI and ISA in the past, you just had the ahc(4) driver (for >>> example). >>> USB vs PCI is the same. It should just be a single manpage for the driver >>> regardless of the attachment. If the driver has separate modules that can >>> be documented in the one manpage, but the list of supported chipsets, etc. >>> is presumably shared hence the shared driver name and common code. In >>> particular, the thing a user sees in dmesg is 'rtwn0', not 'rtwn_pci0' so >>> the manpage needs to be tied to what a user sees as a device name in dmesg. >>> >> >> Yea, the man page should mention the detail that we have separate .ko's, but >> otherwise I agree with John here. > > IIUC, all interfaces should be documented as $foo with an mlink (but no additional > name macro) to if_$foo. I've also been pushing for sound to become represented > the same way for consistency, which christos said (paraphrased) no objection. So someone should comment out/remove the old entry in ObsoleteFiles.inc so that the new man page is not deleted again? -- Bjoern A. Zeeb r15:7