From owner-dev-commits-src-main@freebsd.org Fri Jan 8 20:24:57 2021 Return-Path: Delivered-To: dev-commits-src-main@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 67D3A4D5718; Fri, 8 Jan 2021 20:24:57 +0000 (UTC) (envelope-from kostikbel@gmail.com) Received: from kib.kiev.ua (kib.kiev.ua [IPv6:2001:470:d5e7:1::1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4DCF2d0V40z3CwW; Fri, 8 Jan 2021 20:24:56 +0000 (UTC) (envelope-from kostikbel@gmail.com) Received: from tom.home (kib@localhost [127.0.0.1]) by kib.kiev.ua (8.16.1/8.16.1) with ESMTPS id 108KOjKc044913 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NO); Fri, 8 Jan 2021 22:24:48 +0200 (EET) (envelope-from kostikbel@gmail.com) DKIM-Filter: OpenDKIM Filter v2.10.3 kib.kiev.ua 108KOjKc044913 Received: (from kostik@localhost) by tom.home (8.16.1/8.16.1/Submit) id 108KOjw9044912; Fri, 8 Jan 2021 22:24:45 +0200 (EET) (envelope-from kostikbel@gmail.com) X-Authentication-Warning: tom.home: kostik set sender to kostikbel@gmail.com using -f Date: Fri, 8 Jan 2021 22:24:45 +0200 From: Konstantin Belousov To: Warner Losh Cc: Mateusz Piotrowski <0mp@freebsd.org>, src-committers , 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: References: <202101070924.1079OE4g081849@gitrepo.freebsd.org> <52e99dc8-cd75-a2ab-7670-b81d8aaa8134@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Spam-Status: No, score=-1.0 required=5.0 tests=ALL_TRUSTED,BAYES_00, DKIM_ADSP_CUSTOM_MED,FORGED_GMAIL_RCVD,FREEMAIL_FROM, NML_ADSP_CUSTOM_MED autolearn=no autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on tom.home X-Rspamd-Queue-Id: 4DCF2d0V40z3CwW X-Spamd-Bar: ---- Authentication-Results: mx1.freebsd.org; none X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[] X-BeenThere: dev-commits-src-main@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for the main branch of the src repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 08 Jan 2021 20:24:57 -0000 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).