ports.7/FILES: Expand and refactor into 3 tables Add make.conf, CHANGES, CONTRIBUTING.Md, UPDATING, and Tools/scripts. Refactor the FILES section of the ports reference manual into a bigger table with three sections separated by root directory. Remove preceeding article from all but "the big Kahuna", and root dirs where reasonable. MFC after: 3 days Reported by: adamw Differential Revision: https://reviews.freebsd.org/D55441
Details
Details
Diff Detail
Diff Detail
- Repository
- rG FreeBSD src repository
- Lint
Lint Skipped - Unit
Tests Skipped - Build Status
Buildable 70934 Build 67817: arc lint + arc unit
Event Timeline
Comment Actions
You're totally right. I grepped the doc repo just to be sure, and we don't have anything about using ${DEFAULT_VERSIONS}. If we had something (maybe in the handbook, as it's designed for end-users) we could reference it here instead maybe.
Phrasing feels challenging here, possibly because everything starts with "The"? If that's changeable, even just removing that word from some of the descriptors might make the whole section easier to parse.
| share/man/man7/ports.7 | ||
|---|---|---|
| 596 | The phrasing is a little awkward; "settings" and "to configure" are so similar but just different enough to cause some cognitive dissonance. I don't have any confident alternative though. Ports tree config file? I'm not sure why I am having so much trouble 😕 | |
| 597 | Could we emphasize UPDATING a little more? When something could break users' systems, that's where we warn them and show them the fix. | |
Comment Actions
we don't have anything about using ${DEFAULT_VERSIONS}.
Ok, here's a first try >> https://reviews.freebsd.org/D55443.
maybe in the handbook, as it's designed for end users
I think we can engineer the integrated, always-available, semantically
tagged reference manuals for the kind of end users I want to attract to
our community. It's a really advanced system, it's highly structured and
indexed. Further, a semantic manual is an original BSD feature that's
still impressively ahead of other systems that haven't adopted it have.
And the manual treats the integrated tty, our true UX, as a first class
citizen.
not sure why I am having so much trouble
haha, I've looked at some individual sentences for years thinking
one day I'll get good enough to fix them.
Comment Actions
Split FILES into sections arranged by root directory, so that CHANGES and UPDATING can be at the top, but we can still give this table more structure.
| share/man/man7/ports.7 | ||
|---|---|---|
| 615 | "for patches and/or any additional files" | |
Comment Actions
Improve language for UPDATING and CHANGES, which also kicks the exclaimation mark out a bit father to catch the eye more.
| share/man/man7/ports.7 | ||
|---|---|---|
| 596 | Perhaps use "creating" instead of "developing"---end users may not know what we mean by "developing." | |
| 621–629 | I'd put "The" back in the beginning there so that the grammar matches the others. | |
| 625 | I'm iffy about this one. It's settings used by make, but none of them control make itself. They're settings for the ports framework (bsd.port.mk), controlling how it builds and installs ports. I feel like I'm picking nits at this point. Your work looks fantastic, Alexander. | |
| share/man/man7/ports.7 | ||
|---|---|---|
| 609 | ||
Comment Actions
Fix typos, thanks @arrowd! I'll give everyone a few days to add any more
suggestions or approve, I think this is a major feature for the ports(7)
manual!
| share/man/man7/ports.7 | ||
|---|---|---|
| 626 | Usually I see "ports tree," not "ports-tree." | |