[makefiles] igor -Ry and some other rewording and fixes.

[wblock]

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

21–22

"Now" is not needed.

30

"If not, the distribution file format might require overriding one or more of"

35–36

End the sentence after DISTFILES:

..., or <varname>DISTFILES</varname>.</para>

and delete the next two lines.

41

Break this compound sentence into two sentences:

"default. This is rarely necessary.</para>"

61

s/Package/The package/

62

s/tree, check/tree. Make sure/

78

This whole paragraph is full of asides.

<para><varname>PORTREVISION</varname> is a monotonically increasing value which is reset to 0 with every increase of <varname>PORTVERSION</varname>, typically every time there is a new official vendor release.
If <varname>PORTREVISION</varname> is non-zero, the value is appended to the package name.
Changes to <varname>PORTREVISION</varname> are used by automated tools like &man.pkg-version.8; to determine that a new package is available.</para>

109

<para>Changes in the packing list or the install-time behavior of the package. For example, a change to a script which generates initial data for the package, like &man.ssh.1; host keys.</para>

125

Break compound sentence:

s/differences, that is,/differences. For example,/

169–170

This paragraph would also benefit from breaking out the asides into separate sentences.

181

Break sentences up:

s/bumped because/bumped. Without increasing <varname>PORTREVISION</varname>, the/

212–213

Another paragraph with asides. Not your fault, but fix if you can.

228–231

End the first sentence after "grief". After that...

If the description above was not clear enough, please consult the &a.ports;.</para>

237

s/change/changes/

245–246

This sentence is long and confusing. Break into multiple sentences, and if you show the wrong way, show it first:

For example, do not do ... . The correct way is ... .

393

"think about it" seems a little weak, but I can't think of a better version.

431

Break out aside:

"states the compiled-in defaults. The hyphen is optional.

457

s/follows/follow/

651–653

s/there are/there is/

751

s/to serial/to the serial/

777–779

Remove the emdash and split the sentence:

s/libraries&mdash; they/libraries. They/

"should not" would be okay here, as a recommendation. The emphasis should be on "not" either way.

798–801

Break compound sentence, with the "for example" in the second sentence.

814

Break into two sentences instead of the emdash.

837

use <acronym> tags on FTP and HTTP.

999

s/get/be/

1224

Break sentence at the semicolon.

1318

Insert "the" before CATEGORIES.

1324

Avoid passive voice.

s/will be/is/

1365

"... be deleted and the port placed only in the other subdirectory.</para>

1375–1378

s/clearly cut/clearly defined/

1376

send-pr is gone. "port submission in the bug database" (and a link)?

1500–1501

Break sentence at semicolon.

1511

Remove "from".

1615

s/be added/are included/

1632

"The older expanded format can still be used, although there"

1633

"really is no reason to do so:</para>

1904–1905

I don't understand what this sentence is saying.

1932

It does need the "the" before DISTFILES.

1941–1942

<para>When none of the <varname>DISTFILES</varname> need to be uncompressed, set <varname>EXTRACT_ONLY</varname> to the empty string.</para>

1952

<acronym> tags for FTP and HTTP.

1980

Break sentence at the emdash.

2065

Nice!

2134

Remove "section".

2135

s/the port/the new port's/

2176–2178

Extra "with".

2231

s/these/the/

2691

s/for example,/like/

Should probably have <acronym> tags around GPL.

2861

Good catch!

2881

s/has to/have to/

3199–3200

s/in/is/

(Not yours, I know.)

3277

Nice!

3296

s/is/their/

3298–3299

Break at semicolon.

3299

Remove "this"

3302

Replace &mdash; with comma.

3398

"using variables cleverly, only a very short"

3424

s/Runnig/Running/

3466–3467

<acronym> tags on GNU.

3618

s/can/values can/

3652–3655

"The form shown above is discouraged. The preferred method is using a configure knob to really enable and disable the feature to match the option:"

(I suggest only showing the preferred way and not mentioning the other way.)

4296

s/in to/into/

4331

s/all/all,/

4378–4380

If the port cannot be built when other specific ports are already

4380

s/use/Use/

4382–4384

"Enumerate" is nice, but probably more difficult for translators than "Use package names, not port names or origins."

Actually, that is not clear to me. Package names being a full filename? And above, it says "list the other *port* names". An example would help, along with consistent statements.

4475–4476

"Must" does not seem right. What if DEBUG is set?

s/do/Do/, but that sentence is vague. How do I know when I need to strip binaries manually?

[mat]

Back to Warren. I think I got everything mostly right

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

393

I had the same problem, I ended up with this...

777–779

Maybe igor should look for those, and the semi-colon and say that they're not great 0:-)

1904–1905

EXTRACT_SUFX is normally set to .tar.gz and the only way it is used is line 2511 of bsd.port.mk:

DISTFILES?= ${DISTNAME}${EXTRACT_SUFX}

So if you set DISTFILES for some other reason, EXTRACT_SUFX is never used and you don't need to set it.

3199–3200

No problem, I also correct the few I find :-)

3652–3655

Well, with that example, yes, it would be better not to show the bad example, but, there sure are places where porters need to use this kind of tests, for some reason or another, and I'd rather have an example, of how to do it.

4382–4384

No, not the full file name, the glob is for the package name, for instance, dns/bind99 has:

CONFLICTS= bind9*-9.[45678].* bind9*-sdb-9.[45678].* bind-tools-9.*

the package names are, say, for dns/bind98 : bind98-9.8.7P1_5.

As for an example, it would be nice, yes, but I'll have to either find one that's easy to understand, or make a useful one up.

4475–4476

DEBUG replaces STRIP_CMD with true, I think, or something, that will just be ignored.

Actually, I think I'm going to change that to should, it's more of a recommendation.

4482

Hum, I have no idea, I'm sure people have insane reason to do stuff. Also, it serves as an example for when upstream thought it was clever and used cp, or some other convoluted way to install files. A porter can just run STRIP_CMD some/file in post-install.

[wblock]

I can't tell if changes are being hidden by phabricator's confusing UI, so may have missed some.

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

393

I guess I don't understand what this part about the name is explaining. Why should the first letter be lower case? The nonspecific "think about it" does not tell me the goal. Am I supposed to think about converting the whole thing to lower case? And then... is just thinking about it enough?

777–779

It's been considered. One difficulty is the semicolons that are part of entities. Also, semicolons are only one of the signs of compound sentences. There are colons and parens and commas and lots of others.

[mat]

In D643#15, @wblock wrote:

I can't tell if changes are being hidden by phabricator's confusing UI, so may have missed some.

Well, if you click on the link CHANGES SINCE LAST UPDATE you got in the email that has a subject Differential] [Updated, 803 lines] D643: [makefiles] igor -Ry and some other rewording and fixes. you should get the diff with the version with your changes on the left, and my new changes on the right.

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

393

Well, hum, the idea is that you should really not have a package name that starts with a capital letter. Then, you should refrain from having capital letter later in the name. So, well, I don't really know what you're supposed to be thinking about :-)

[wblock]

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

22

design *of* the new

42

The "if ever" is redundant but can be kept if you feel it is needed. (It's a subset of "rarely".)

224

"for example," is not needed in this line.

251

Double "use".

253

"to use" is not needed.

394

I still don't see *why* the first letter should not be upper case. We have ports that actually break that rule, like ImageMagick. Is it for ASCII sorting?

2136

s/port/port's/

3585–3586

s/time/times/

[mat]

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

42

Yes, I'll keep it, people should almost never need to do that :-)

394

Ok, yes, I've discussed it with my fellow portmgr, and it is not needed any more, it seems. Rewording it. (Well, more like axing it.)

[mat]

back

[wblock]

Please build-test and commit.

[mat]

Closed by commit rD45627 (authored by @mat).