svn commit: r362809 - head/contrib/mandoc
Rodney W. Grimes
freebsd at gndrsh.dnsmgr.net
Wed Jul 1 23:07:22 UTC 2020
> 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 at 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 at 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 at freebsd.org
>
--
Rod Grimes rgrimes at freebsd.org
More information about the svn-src-head
mailing list