Date: Fri, 8 Jan 2021 22:24:45 +0200 From: Konstantin Belousov <kostikbel@gmail.com> To: Warner Losh <imp@bsdimp.com> Cc: Mateusz Piotrowski <0mp@freebsd.org>, src-committers <src-committers@freebsd.org>, dev-commits-src-all@freebsd.org, dev-commits-src-main@freebsd.org Subject: Re: git: 74bd20769706 - main - Reference newfs_msdos(8) from the newfs(8) manual Message-ID: <X/i/jU5j3p2NsHyy@kib.kiev.ua> In-Reply-To: <CANCZdfrGAhcmdQvsLWepEx--sRD7gan2zVCbFsbBKOwNcM0Cow@mail.gmail.com> References: <202101070924.1079OE4g081849@gitrepo.freebsd.org> <X/dQAejFbWFxM8Uu@kib.kiev.ua> <52e99dc8-cd75-a2ab-7670-b81d8aaa8134@FreeBSD.org> <CANCZdfrGAhcmdQvsLWepEx--sRD7gan2zVCbFsbBKOwNcM0Cow@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Jan 08, 2021 at 07:54:41AM -0700, Warner Losh wrote: > On Fri, Jan 8, 2021 at 5:51 AM Mateusz Piotrowski <0mp@freebsd.org> wrote: > > > Hello Konstantin, > > > > On 1/7/21 7:16 PM, Konstantin Belousov wrote: > > > On Thu, Jan 07, 2021 at 09:24:14AM +0000, Mateusz Piotrowski wrote: > > >> The branch main has been updated by 0mp (doc, ports committer): > > >> > > >> URL: > > https://cgit.FreeBSD.org/src/commit/?id=74bd20769706041108a573601cf0b61c755bdc56 > > >> > > >> commit 74bd20769706041108a573601cf0b61c755bdc56 > > >> Author: Mateusz Piotrowski <0mp@FreeBSD.org> > > >> AuthorDate: 2021-01-07 09:22:20 +0000 > > >> Commit: Mateusz Piotrowski <0mp@FreeBSD.org> > > >> CommitDate: 2021-01-07 09:24:07 +0000 > > >> > > >> Reference newfs_msdos(8) from the newfs(8) manual > > > Why ? newfs is not the interface to create arbitrary kind of filesystem, > > > it is just UFS writer. > > > > I think that it is beneficial nevertheless. Now users can discover other > > newfs_* commands FreeBSD > > offers. Also, newfs_msdos(8) already references newfs(8) (there are only > > two items in the SEE ALSO > > section there, the other one being gpart(8)). > > > > From my perspective it is not too bad to have this reference in the newfs > > manual. It seems like > > it's also something some FreeBSD users expect to see in the manual page as > > we received a bug report > > for that. > > > > I can revert this patch and also remove newfs(8) from the newfs_msdos > > manual while at it if desired. > > Perhaps newfs commands are easy enough to find so this patch only hurts > > the readability of the manual... > > > > I think it's a good change because many other filesystem manipulation > commands will do arbitrary filesystems. Since it breaks this symmetry, > having the xref is fine. Your reply just highlights my point. As is, the cross-reference is unmotivated and cause questions what is so special for msdosfs that UFS newfs requires mentioning of it. If there is some explanation along the lines that newfs is the common name prefix for utilities creating filesystems, with the suffix being the type of fs, for instance newfs_msdos(8) etc, then it becomes useful and reasonable. Note that it is not really true that 'many' utilities follow this pattern, I can only think of newfs, fsck, and partially mount (for mount it is more complicated and probably requires providing too much implementation details to explain).
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?X/i/jU5j3p2NsHyy>