patches to Handbook ports section: part 1

[linimon]

Summary

This patch attempts to clarify wording in the ports section of the Handbook.

The presentation assumes more knowledge on the part of a new user to FreeBSD than it should. Some of the text, while correct, is still too easy to misunderstand.

This patch attempts to add some clarity. The overall sense of the text does not change.

[wblock]

chapter.xml

262 ↗

(On Diff #23064)

I suggest saying "a *particular* application":

repository for a particular application like <application>Subversion</application>:</para>

406 ↗

(On Diff #23064)

See where you are going, but it's still not quite clear. The problem is probably that "port management tools" is ambiguous, and the difference between them and pkg is not made clear here. The context of the whole paragraph will help to see how this should be changed.

421 ↗

(On Diff #23064)

This immediately makes the reader wonder "uh-oh, which versions?" Maybe "with versions of &os; since 9.x"? (or whatever it was).

427 ↗

(On Diff #23064)

The removed part is helpful in telling the reader why it might fail. How about just "On &os; versions before 9.x,"?

476 ↗

(On Diff #23064)

Could use more details. Maybe just

binary packages from the &os; package mirrors.

1182 ↗

(On Diff #23064)

Comma not needed: s/system,/system/

1374 ↗

(On Diff #23064)

(Not yours, I know)
Passive->active: s/will collect/collect/

1375 ↗

(On Diff #23064)

Passive->active:

<application>Portupgrade</application> can

1392 ↗

(On Diff #23064)

(Not yours, sorry)
Passive->active: s/will prompt/prompts/

1396 ↗

(On Diff #23064)

Does pkg_cutleaves work again?

1443 ↗

(On Diff #23064)

The original is shorter, but ambiguous. Maybe "compilation jails"?

1546 ↗

(On Diff #23064)

Passive->active (ignoring linewrap):

While running, pressing keycombo action="simul"><keycap>Ctrl</keycap><keycap>t</keycap></keycombo>
displays the current state of the build.

1552 ↗

(On Diff #23064)

"the" not needed: s/the packages/packages/

1578 ↗

(On Diff #23064)

Absolutely agreed, "setup" is a noun, "set up" is a verb. And although it looks like a whitespace-only change, it is actually changing content.

1610 ↗

(On Diff #23064)

"some" is probably not needed, just "In cases where".

1676 ↗

(On Diff #23064)

This sounds a little weird, but it's hard to think of something shorter. Maybe

instead by a group maintainer represented by a <link

[linimon]

Various replies in preparation for the next patch.

chapter.xml

406 ↗

(On Diff #23064)

I'll attempt a rewrite in the next patch.

421 ↗

(On Diff #23064)

OK, you've caught me hand-waving.

Not all of our archs have pkg repositories available on the FreeBSD mirrors. I am only aware of sparc64 (since I build that repo myself, privately) but without a full knowledge of every combination I can't say with authority. armeb? pc98? I don't know.

I will accept suggestions.

1396 ↗

(On Diff #23064)

I was not aware it was broken?

1552 ↗

(On Diff #23064)

Well, packages may have been available before. In the next patch let's try "the new".

[linimon]

Updated diff taking into account feedback.

New content:

• explanation of which version/arch combinations will bootstrap correctly
• note about startup/shutdown scripts

[linimon]

clarification of newest changes

chapter.xml

421 ↗

(On Diff #23064)

See the newly added note, below.

[wblock]

Done through line 494, at which point Phabricator insists I am already editing another comment and so can't add one. Even though I am not. Yay Phabricator! Review continued in a separate batch.

chapter.xml

74 ↗

(On Diff #23132)

s/or/or a/

407 ↗

(On Diff #23132)

"May" often implies permission. How about:

managing packages with <application>pkg</application> alone might be
sufficient.</para>

410 ↗

(On Diff #23132)

"and/or" can just be "or", it's not an xor.

411 ↗

(On Diff #23132)

This can be simpler:

a separate <emphasis>port management tool</emphasis> is needed.

426 ↗

(On Diff #23132)

Simplify:

download and install <application>pkg</application> and
its manual pages.  This utility is designed to work

432 ↗

(On Diff #23132)

Should be plurals: versions and architectures

441 ↗

(On Diff #23132)

I suspect the reader does not know what "does not work" really means. No idea if pkg has specific messages on some architectures or something, but that could help. Or maybe just be specific on how to tell if it *does* work.

489 ↗

(On Diff #23132)

Needs a comma:

<para>By default, <application>pkg</application> uses the

491 ↗

(On Diff #23132)

Use <quote>repository</quote>. Although I'm not sure if that is the right way to do this, either.

262 ↗

(On Diff #23064)

The repeated pauses of the commas make this somewhat halting. Try "like", you'll like it.

[wblock]

chapter.xml

494 ↗

(On Diff #23132)

Missing a period at the end of the sentence, and I would put the <xref at the beginning of that line for readability if it will fit in 70 columns:

<xref linkend="ports-poudriere"/>.</para>

738 ↗

(On Diff #23132)

"termed" is an unusual verb. How about just "called"?

740 ↗

(On Diff #23132)

"under" is a little weird, but I understand the attempt to avoid defining categories. "By default" is probably not needed. How about:

These files are grouped into categories and stored in

842 ↗

(On Diff #23132)

Again, "called" is simpler and probably easier for translators and non-native speakers:

called a <emphasis>port skeleton</emphasis>. Each port

1668 ↗

(On Diff #23132)

Use <replaceable> around the "listname".

1671 ↗

(On Diff #23132)

s/ports shown as maintained by/maintained by/

[linimon]

Add changes in response to wblock comments.

Add note about startup and stop scripts during upgrade.

[linimon]

The rendered version may be found at https://people.freebsd.org/~linimon/tmp/ports-using.D8838.html .

[wblock]

chapter.xml

410 ↗

(On Diff #23218)

s/package/packages/

411 ↗

(On Diff #23218)

This was mine, but I think "can" is a better word than "might".

437 ↗

(On Diff #23218)

This is XML, so I'm pretty sure this link can just be

<link xlink:href="http://pkg.freebsd.org/" />.</para>

Please test, though.

449 ↗

(On Diff #23218)

"May" usually implies permission rather than possibility. How about saying "A typical error message looks like this:"? Or, for that matter, does showing the error message help the user much? Maybe we can just leave it out?

462 ↗

(On Diff #23218)

new format so new tools are aware of installed packages.

486 ↗

(On Diff #23218)

s/listed/shown/ to avoid repeated redundancy of "list".

487 ↗

(On Diff #23218)

Break this sentence here:
"finished. These applications must be manually reinstalled."

492 ↗

(On Diff #23218)

s/format/database/

499 ↗

(On Diff #23218)

s/on/from/

500 ↗

(On Diff #23218)

<literal> is not really the right tag here. It's a term, so I would use <emphasis>.

502 ↗

(On Diff #23218)

On lines where the xref will fit, I usually move it to the next line so it's easier to read. So:

...see
<xref linkend="ports-poudriere"/>.</para>

1434 ↗

(On Diff #23218)

Passive...

s/should/will/

1572 ↗

(On Diff #23218)

As a reader, I dislike the "something like" because it is vague and I don't know what should be similar to the example and what would be different. For some reason, just "like" seems less ambiguous.

[linimon]

Updated incorporating all suggestions.

[wblock]

chapter.xml

413 ↗

(On Diff #23710)

Flip this around to describe pkg first:

<application>pkg</application>, which only works with binary packages,
is not a replacement for port management tools that can be used to install
software from both binary packages and the Ports Collection.</para

443 ↗

(On Diff #23710)

"probably" still leaves some concern for the reader. And this section does not help the reader resolve the problem, so I'm still not sure what it accomplishes. "Yep, that's the problem."

480 ↗

(On Diff #23710)

Passive -> active:
s/will be/is/
s/has finished/finishes/

1559 ↗

(On Diff #23710)

<replaceable> tags should also be used in this second example filename.

[linimon]

• Incorporate latest feedback
• Slight clarification of bootstrap process

[linimon]

full-context diff