On Thu, 6 Mar 2025, Alexander Ziaee wrote:
On 2025-03-04 12:07 -05:00 EST, "Warner Losh" <i...@bsdimp.com> wrote:
On Tue, Mar 4, 2025 at 8:23 AM John Baldwin <j...@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 <zi...@freebsd.org>
AuthorDate: 2025-02-19 15:54:27 +0000
Commit: Alexander Ziaee <zi...@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
