Re: git: 4262dbc57982 - main - wifi manuals: Mlink + document description consistency

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.

-- 
John Baldwin