Date: Thu, 06 Mar 2025 23:47:31 +0000 (UTC) From: "Alexander Ziaee" <adziaee@runbox.com> To: "Warner Losh" <imp@bsdimp.com>, "John Baldwin" <jhb@freebsd.org> Cc: "Bjoern A. Zeeb" <bz@freebsd.org>, "Herbert J. Skuhra" <herbert@gojira.at>, "Alexander Ziaee" <ziaee@freebsd.org>, "Adrian Chadd" <adrian@freebsd.org>, "src-committers" <src-committers@freebsd.org>, "dev-commits-src-all" <dev-commits-src-all@freebsd.org>, "dev-commits-src-main" <dev-commits-src-main@freebsd.org>, "Christos Margiolis" <christos@freebsd.org> Subject: Re: git: 4262dbc57982 - main - wifi manuals: Mlink + document description consistency Message-ID: <E1tqKw7-0006H0-Ae@rmmprod05.runbox> In-Reply-To: <CANCZdfpos8fqO7a=k96K_SiFwGQ9HijcWayeYOjcJQM35P=gVQ@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2025-03-04 12:07 -05:00 EST, "Warner Losh" <imp@bsdimp.com> wrote: > On Tue, Mar 4, 2025 at 8:23=E2=80=AFAM John Baldwin <jhb@freebsd.org> wro= te: >=20 >> 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=3D4262dbc57982383eb61a8b7806de6d= d4b7802da8 >> >>> >> >>> 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", exce= pt >> 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+=3Dptnet.4 if_ptnet.4 >> >>> MLINKS+=3Dral.4 if_ral.4 >> >>> MLINKS+=3Dre.4 if_re.4 >> >>> MLINKS+=3Drl.4 if_rl.4 >> >>> -MLINKS+=3Drtwn_pci.4 if_rtwn_pci.4 >> >>> +MLINKS+=3Drtw88.4 if_rtw89.4 >> >>> +MLINKS+=3Drtw89.4 if_rtw89.4 >> >>> +MLINKS+=3Drtwn.4 if_rtwn.4 >> >> ^^^^^^^^^ >> >> $ grep if_rtwn.4 ObsoleteFiles.inc >> >> OLD_FILES+=3Dusr/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 kn= ow >> > better). >> > >> > But everyone is just referring to the driver as rtwn and I fear if the= re >> > 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 driv= er >> regardless of the attachment. If the driver has separate modules that c= an >> be documented in the one manpage, but the list of supported chipsets, et= c. >> 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 dme= sg. >> >=20 > 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 add= itional name macro) to if_$foo. I've also been pushing for sound to become represen= ted the same way for consistency, which christos said (paraphrased) no objectio= n.=
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?E1tqKw7-0006H0-Ae>