Date: Wed, 1 Jul 2020 16:07:12 -0700 (PDT) From: "Rodney W. Grimes" <freebsd@gndrsh.dnsmgr.net> To: Gordon Bergling <gbe@freebsd.org> Cc: Warner Losh <imp@bsdimp.com>, "Rodney W. Grimes" <rgrimes@freebsd.org>, src-committers <src-committers@freebsd.org>, svn-src-all <svn-src-all@freebsd.org>, svn-src-head <svn-src-head@freebsd.org> Subject: Re: svn commit: r362809 - head/contrib/mandoc Message-ID: <202007012307.061N7Cpk058637@gndrsh.dnsmgr.net> In-Reply-To: <20200701212847.GA1751@lion.0xfce3.net>
next in thread | previous in thread | raw e-mail | index | archive | help
> On Wed, Jul 01, 2020 at 11:58:05AM -0600, Warner Losh wrote: > > On Wed, Jul 1, 2020 at 8:51 AM Rodney W. Grimes <freebsd@gndrsh.dnsmgr.net> > > wrote: > > > > > > On Tue, Jun 30, 2020 at 03:56:17PM -0700, Rodney W. Grimes wrote: > > > > > [ Charset UTF-8 unsupported, converting... ] > > > > > > Author: gbe (doc committer) > > > > > > Date: Tue Jun 30 18:08:59 2020 > > > > > > New Revision: 362809 > > > > > > URL: https://svnweb.freebsd.org/changeset/base/362809 > > > > > > > > > > > > Log: > > > > > > Mention FreeBSD in the HISTORY sections of apropos(1) and > > > makewhatis(8). > > > > > > > > > > > > PR: 223520, 223521 > > > > > > Reviewed by: bcr (mentor) > > > > > > Approved by: bcr (mentor) > > > > > > Differential Revision: https://reviews.freebsd.org/D25521 > > > > > > > > > > > > Modified: > > > > > > head/contrib/mandoc/apropos.1 > > > > > > head/contrib/mandoc/makewhatis.8 > > > > > > > > > > > > Modified: head/contrib/mandoc/apropos.1 > > > > > > > > > ============================================================================== > > > > > > --- head/contrib/mandoc/apropos.1 Tue Jun 30 17:21:28 2020 > > > (r362808) > > > > > > +++ head/contrib/mandoc/apropos.1 Tue Jun 30 18:08:59 2020 > > > (r362809) > > > > > > @@ -15,7 +15,7 @@ > > > > > > .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, > > > ARISING OUT OF > > > > > > .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. > > > > > > .\" > > > > > > -.Dd $Mdocdate: November 22 2018 $ > > > > > > +.Dd $Mdocdate: June 30 2020 $ > > > > > > .Dt APROPOS 1 > > > > > > .Os > > > > > > .Sh NAME > > > > > > @@ -493,6 +493,12 @@ The options > > > > > > .Fl acfhIKklOTWw > > > > > > appeared in > > > > > > .Ox 5.7 . > > > > > > +.Pp > > > > > > +The > > > > > > +.Nm > > > > > > +utility was integrated into > > > > > > +.Fx 11.1 > > > > > > +as part of the switch to mandoc. > > > > > > > > > > Huh? FreeBSD has had apropos since 1.0 and my 5.4 system clearly has > > > it: > > > > > freebsd {110}% uname -a > > > > > FreeBSD pdx.rh.CN85.dnsmgr.net 5.4-RELEASE-p8 FreeBSD 5.4-RELEASE-p8 > > > #1: Mon Jul 1 17:58:50 PDT 2019 root@pdx.rh.CN85.dnsmgr.net:/usr/src/sys/i386/compile/PDXMXPIE > > > i386 > > > > > pdx.rh.CN85.dnsmgr.net:freebsd {111}% which apropos > > > > > /usr/bin/apropos > > > > > > > > > > And a man page for it too: > > > > > APROPOS(1) FreeBSD General Commands Manual > > > APROPOS(1) > > > > > > > > > > NAME > > > > > apropos, whatis -- search the whatis database > > > > > > > > > > SYNOPSIS > > > > > apropos keyword ... > > > > > whatis keyword ... > > > > > > > > > > DESCRIPTION > > > > > apropos searches a set of database files containing short > > > descriptions of > > > > > system commands for keywords and displays the result on the > > > standard out- > > > > > put. whatis displays only complete word matches. > > > > > > > > > > keyword really is an extended regular expression, please read > > > grep(1) > > > > > manual page for more information about its format. > > > > > > > > > > DIAGNOSTICS > > > > > The apropos utility exits 0 on success, and 1 if no keyword > > > matched. > > > > > > > > > > SEE ALSO > > > > > grep(1), makewhatis(1), man(1) > > > > > > > > > > FreeBSD 5.4 January 15, 1991 > > > FreeBSD 5.4 > > > > > > > > > > > .Sh AUTHORS > > > > > > .An -nosplit > > > > > > .An Bill Joy > > > > > > > > > > > > > > That is true, but the version of 'apropos' we have currently in base is > > > based on mandoc, > > > > which was imported around September 2018. Due to the nature of > > > contributed code I > > > > thought it would be best to document only the history when it was > > > integrated into > > > > FreeSBD. The same applies for 'makewhatis'. > > > > > > That is not what has been done in other places when code is > > > changed/replaced, > > > the HISTORY section is not specific to "FreeBSD's version" of this > > > function. > > > > > > We often have "An ls command appeared in Version 1 AT&T UNIX." Our source > > > code and man page is not from that, but that is the history of ls. > > > > > > This *could* be amended and *should* be amended to reflect that apropos, > > > and makewhatis got *updated* by a switch to the mandoc versions, but it > > > is misleading to say it was intergrated with the switch to mandoc as that > > > implies it did not exist before this action. > > > > > > > I tend to agree with Rod here. These appeared in X the first time, but > > noting they were replaced in version X with Y is the best way to address > > the current provenance of the code... > > > > Warner > > OK, I see your arguments. How about the following addition for HISTORY section, > > The apropos utility was integrated into FreeBSD 11.1 as part of the > switch to mandoc. Before the switch to mandoc apropos was available since > FreeBSD 1.0. This still implies that it originated with the switch to mandoc, though there is other context that indicates it did not. There is already a pretty good history section there, I am not sure what your trying to clarify. Even the Authors section reflects the history accurately. I do not see that this is adding any great value to the HISTORY for either apropos or makewhatis. > > Any suggestions on how to describe the history more precise are very welcome. The history appears to be described accurately already. > --Gordon > > > > > > > Modified: head/contrib/mandoc/makewhatis.8 > > > > > > > > > ============================================================================== > > > > > > --- head/contrib/mandoc/makewhatis.8 Tue Jun 30 17:21:28 2020 > > > (r362808) > > > > > > +++ head/contrib/mandoc/makewhatis.8 Tue Jun 30 18:08:59 2020 > > > (r362809) > > > > > > @@ -15,7 +15,7 @@ > > > > > > .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, > > > ARISING OUT OF > > > > > > .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. > > > > > > .\" > > > > > > -.Dd $Mdocdate: May 17 2017 $ > > > > > > +.Dd $Mdocdate: June 30 2020 $ > > > > > > .Dt MAKEWHATIS 8 > > > > > > .Os > > > > > > .Sh NAME > > > > > > @@ -211,6 +211,12 @@ and the options > > > > > > .Fl aCDnQT > > > > > > in > > > > > > .Ox 5.6 . > > > > > > +.Pp > > > > > > +The > > > > > > +.Nm > > > > > > +utility was integrated into > > > > > > +.Fx 11.1 > > > > > > +as part of the switch to mandoc. > > > > > > > > > > Ditto > > > > > > > > > > > .Sh AUTHORS > > > > > > .An -nosplit > > > > > > .An Bill Joy > > > -- > > > Rod Grimes > > > rgrimes@freebsd.org > -- Rod Grimes rgrimes@freebsd.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202007012307.061N7Cpk058637>