Update HISTORY sections by requested changes from r362809.
PR: 223520, 223521
Diff Detail
Diff Detail
- Lint
No Lint Coverage - Unit
No Test Coverage - Build Status
Buildable 32397 Build 29878: arc lint + arc unit
Event Timeline
Comment Actions
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.
| contrib/mandoc/apropos.1 | ||
|---|---|---|
| 499 | 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. | |
Comment Actions
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.
Comment Actions
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.
Comment Actions
| contrib/mandoc/apropos.1 | ||
|---|---|---|
| 498–500 | I think you could just skip this part, mandoc covers the pre-FreeBSD history already. | |
| 500–502 | 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 | ||
| 217–220 | 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 | ||
|---|---|---|
| 500–502 | It seems Phab can't edit inline comments - missing 'd' on the end of integrated. | |
Comment Actions
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.
| contrib/mandoc/makewhatis.8 | ||
|---|---|---|
| 217–220 | I used man.freebsd.org to determine the first appearance of 'makewhatis'. | |
| contrib/mandoc/makewhatis.8 | ||
|---|---|---|
| 218 | 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. | |
Comment Actions
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?
Comment Actions
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.
Comment Actions
Tiny local patches in an areas that aren't likely to regularly result in conflicts are quite easy / low-cost to carry.