Page MenuHomeFreeBSD

apropos(1) and makewhatis(8): Update HISTORY sections
AbandonedPublic

Authored by gbe on Jul 5 2020, 7:36 AM.

Details

Reviewers
imp
rgrimes
danfe
karels
emaste
Group Reviewers
manpages
Summary

Update HISTORY sections by requested changes from r362809.

PR: 223520, 223521

Test Plan

mandoc output review

Diff Detail

Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 32399
Build 29880: arc lint + arc unit

Event Timeline

gbe requested review of this revision.Jul 5 2020, 7:36 AM
gbe created this revision.

I do not believe we normally document this type of information in the HISTORY section of manual pages. The history sections of these man pages are already rich with information, especially when you add the history included in the Authors section.

karels requested changes to this revision.Jul 5 2020, 12:20 PM
karels added a subscriber: karels.
karels added inline comments.
contrib/mandoc/apropos.1
498

This is completely incorrect, or at least highly misleading. These utilities appeared long before FreeBSD 1.0, and Bill Joy never wrote code for FreeBSD. Please restore the original and correct history section about BSD (not FreeBSD) and continue from there if necessary.

This revision now requires changes to proceed.Jul 5 2020, 12:20 PM

Sorry, I was thinking that the original text was gone; I see that it is here. It is still misleading, or at least poorly worded, to say that these commands "appeared" in FreeBSD 1.0. Essentially every command in 4.4BSD-Lite was also in FreeBSD 1.0, but we don't bother saying so; it adds no useful information. The reference to 1.0 should be deleted.

It was decided that the updates to apropos(1) and makewhatis(8) should be reverted, so this revision is abandoned.

@karels anyway, thanks for the feedback.

As far as I can tell objections from @rgrimes and @karels are to unclear text that implies these commands were introduced either in FreeBSD 1.x and 11.x, not to improving the documentation of their history in FreeBSD in general. IMO this should be reopened with updated text.

contrib/mandoc/apropos.1
498–500

I think you could just skip this part, mandoc covers the pre-FreeBSD history already.

499–501

I think this part is fine or something like

This version of the
.Nm
utility was integrate into
.Fx 11.1
as part of the switch to mandoc.
contrib/mandoc/makewhatis.8
216–218

Did we really have apropos but not makewhatis in 1.0? Not that it really matters, like above I think we could just omit this.

contrib/mandoc/apropos.1
499–501

It seems Phab can't edit inline comments - missing 'd' on the end of integrated.

Hmm, I see @rgrimes commented on that above. I disagree with that take - when we brought this version into FreeBSD is much more useful/relevant information (to readers of this man page in FreeBSD) than that OpenBSD rewrote it in Perl in OpenBSD 2.7.

  • Update the HISTORY sections as suggested by emaste
gbe marked 3 inline comments as done.Jul 18 2020, 11:50 AM
gbe added inline comments.
contrib/mandoc/makewhatis.8
216–218

I used man.freebsd.org to determine the first appearance of 'makewhatis'.

contrib/mandoc/makewhatis.8
216–217

I am highly skeptical that there was no makewhatis in 1.0 if it was in BSD before that. I don't think this sentence adds any useful information. I would omit it, as emaste suggested.

gbe marked an inline comment as done.
  • makewhatis(8): Rework the HISTORY section to match apropos(1).
gbe marked an inline comment as done.Jul 18 2020, 12:22 PM
This revision is now accepted and ready to land.Jul 18 2020, 12:51 PM

@rgrimes and @imp would you be fine with this differential?

I doesn't like to walk through a minefield, again, so, first, do you appreciate the following change? ;-)

Cheers,

--Gordon

I have no objection to it, but it is still not totally factual, more than likely it was "intergrated" into FreeBSD Current/Head when it was at 12 and merged back to stable/11 and first appeared in a FreeBSD release at 11.1. I still do not see any added value to the history of mandoc by this change, and it just makes FreeBSD have a local diff to the mandoc from witch it was derived. Speaking of which, shouldn't this be on a vendor branch?

I have no objection to it, but it is still not totally factual, more than likely it was "intergrated" into FreeBSD Current/Head when it was at 12 and merged back to stable/11 and first appeared in a FreeBSD release at 11.1. I still do not see any added value to the history of mandoc by this change, and it just makes FreeBSD have a local diff to the mandoc from witch it was derived. Speaking of which, shouldn't this be on a vendor branch?

The local patch is a valid point. Recently I had a small conversation with schwarze@openbsd.org about the integration of this change in the upstream sources, which he refuses. So if we would integrate that change we would have to reapply it every time we update mandoc.

The original PRs 223520 and 223521 were from wosch@ who pointed out that some history was lost since he has written makewhatis some time ago.

I would like to put this again to discussion, because I don't know how much hassle local patches generate.

Tiny local patches in an areas that aren't likely to regularly result in conflicts are quite easy / low-cost to carry.