Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 1 Jul 2020 23:28:47 +0200
From:      Gordon Bergling <gbe@freebsd.org>
To:        Warner Losh <imp@bsdimp.com>
Cc:        "Rodney W. Grimes" <rgrimes@freebsd.org>, Gordon Bergling <gbe@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:  <20200701212847.GA1751@lion.0xfce3.net>
In-Reply-To: <CANCZdfrm3EnKtXoOtR3Tp6H_4V4=wFEY1TRbGk4=O=p7iW77kA@mail.gmail.com>
References:  <20200701074920.GB72275@lion.0xfce3.net> <202007011451.061EpIYF056897@gndrsh.dnsmgr.net> <CANCZdfrm3EnKtXoOtR3Tp6H_4V4=wFEY1TRbGk4=O=p7iW77kA@mail.gmail.com>

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.

Any suggestions on how to describe the history more precise are very welcome.

--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



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20200701212847.GA1751>