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

I suggest saying "a *particular* application":

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

406

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

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

427

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

476

Could use more details. Maybe just

binary packages from the &os; package mirrors.

1182

Comma not needed: s/system,/system/

1374

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

1375

Passive->active:

<application>Portupgrade</application> can

1392

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

1396

Does pkg_cutleaves work again?

1443

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

1546

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

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

1578

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

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

1676

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

I'll attempt a rewrite in the next patch.

421

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

I was not aware it was broken?

1552

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

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

s/or/or a/

262

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

407

"May" often implies permission. How about:

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

410

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

411

This can be simpler:

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

426

Simplify:

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

432

Should be plurals: versions and architectures

441

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

Needs a comma:

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

491

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

[wblock]

chapter.xml

494

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

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

740

"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

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

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

1668

Use <replaceable> around the "listname".

1671

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

s/package/packages/

411

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

437

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

"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

new format so new tools are aware of installed packages.

486

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

487

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

492

s/format/database/

499

s/on/from/

500

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

502

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

Passive...

s/should/will/

1572

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

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

"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

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

1559

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

[linimon]

• Incorporate latest feedback
• Slight clarification of bootstrap process

[linimon]

full-context diff