Add documentation of pkg-{pre,post}-[de]install[.lua]

[pauamma_gundo.com]

Summary

PR: 265476

Reported by: Felix Palmen <[e-mail]>

Test Plan

igor documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
make all
lynx # eyeball that section

[pauamma_gundo.com]

Need to correct on commit and push: author is zirias

[grahamperrin]

I guess, the same suggestions here as at https://reviews.freebsd.org/D36770#835842 …

[pauamma_gundo.com]

Waiting for review from ports people before I update.

[bapt]

I do like what I see, I think we should also mention that the *-pre-* or *-post-* are preferred over the simple pkg-install and pkg-deinstall

[pauamma_gundo.com]

In D36769#835846, @grahamperrin wrote:

I guess, the same suggestions here as at https://reviews.freebsd.org/D36770#835842 …

Since these seem to mostly address my copyediting of zirias' submission I'll address them there.

[pauamma_gundo.com]

In D36769#838779, @bapt wrote:

I do like what I see, I think we should also mention that the *-pre-* or *-post-* are preferred over the simple pkg-install and pkg-deinstall

I'll add that to the other review to keep this one the same as zirias' original text.

[pauamma_gundo.com]

*ping* SME reviewers and mentors

[bcr]

I like these additions, thanks!
A few fixes provided in the comments.

documentation/content/en/books/porters-handbook/pkg-files/_index.adoc

226

A comma before the "and" makes it a list.

233

We discourage the use of "you" in our docs.
A rewrite could start with: "Instead of ..."

234

Another "you", easily fixed here: "Use ... to run a lua script instead of a shell script."

237

I think active voice is better: "These scripts are automatically added to the package."

241–242

Instead of "you" in here, just drop it and the rest of the sentence can remain as it is.

246

Another comma here before the "and".

250

s/will be run/runs/

253–259

s/will be set/is set/

255

"When using ..., respectively."
to avoid the use of "you".

256

Another "you" instance.

259

are automatically added

263–264

Same as above, dropping the "you".

[zirias]

JFTR, my initial PR only contained "minimal" changes to add the new information. I'm totally fine with any rewording of course if it improves the quality of the docs (as long as the information is still correct, which it is as far as I can see!). Just maybe, as this takes a *lot* of time: could it be possible to separate the steps of adding the new info and rewording/improving the docs in general?

[pauamma_gundo.com]

I'm deliberately leaving this one as originally submitted and making all the copyediting changes in https://reviews.freebsd.org/D36770. I plan to push both at the same time, hopefully soon. @bcr, can you check all your suggestions are there? (Some were already there in a different form, and I haven't touched them yet. If they don't work for you as-is, I can adjust.)

documentation/content/en/books/porters-handbook/pkg-files/_index.adoc

226

Now fixed in https://reviews.freebsd.org/D36770.

233

Already fixed in https://reviews.freebsd.org/D36770.

234

Ditto.

237

That's still passive, but I agree present reads a bit better. Now fixed in https://reviews.freebsd.org/D36770.

241–242

Already fixed in https://reviews.freebsd.org/D36770.

246

Now fixed in https://reviews.freebsd.org/D36770.

250

Went for "is run" instead in https://reviews.freebsd.org/D36770.

253–259

Now fixed in https://reviews.freebsd.org/D36770.

255

Already fixed in https://reviews.freebsd.org/D36770.

256

Ditto.

259

Now fixed in https://reviews.freebsd.org/D36770.

263–264

Already fixed in https://reviews.freebsd.org/D36770.

[bcr]

Looks good now!