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

[wblock]

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

21

"Now" is not needed.

30

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

35

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

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

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

228

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

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/

663

s/there are/there is/

763

s/to serial/to the serial/

789

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.

810

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

826

Break into two sentences instead of the emdash.

849

use <acronym> tags on FTP and HTTP.

1011

s/get/be/

1236

Break sentence at the semicolon.

1330

Insert "the" before CATEGORIES.

1336

Avoid passive voice.

s/will be/is/

1377

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

1387

s/clearly cut/clearly defined/

1388

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

1512

Break sentence at semicolon.

1523

Remove "from".

1627

s/be added/are included/

1644

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

1645

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

1916

I don't understand what this sentence is saying.

1944

It does need the "the" before DISTFILES.

1953

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

1964

<acronym> tags for FTP and HTTP.

1992

Break sentence at the emdash.

2077

Nice!

2146

Remove "section".

2147

s/the port/the new port's/

2188

Extra "with".

2243

s/these/the/

2703

s/for example,/like/

Should probably have <acronym> tags around GPL.

2873

Good catch!

2893

s/has to/have to/

3211

s/in/is/

(Not yours, I know.)

3289

Nice!

3308

s/is/their/

3310

Break at semicolon.

3311

Remove "this"

3314

Replace &mdash; with comma.

3410

"using variables cleverly, only a very short"

3436

s/Runnig/Running/

3478

<acronym> tags on GNU.

3630

s/can/values can/

3664

"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.)

4308

s/in to/into/

4343

s/all/all,/

4390

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

4392

s/use/Use/

4394

"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.

4487

"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...

789

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

1916

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.

3211

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

3664

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.

4394

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.

4487

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.

4494

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?

789

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?

2148

s/port/port's/

3597–3598

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).