Skip site navigation (1)Skip section navigation (2)
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>