Page MenuHomeFreeBSD

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

Authored by mat on Aug 20 2014, 3:05 PM.

Diff Detail

Repository
rD FreeBSD doc repository - subversion
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
21 ↗(On Diff #1279)

"Now" is not needed.

30 ↗(On Diff #1279)

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

35 ↗(On Diff #1279)

End the sentence after DISTFILES:

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

and delete the next two lines.

41 ↗(On Diff #1279)

Break this compound sentence into two sentences:

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

61 ↗(On Diff #1279)

s/Package/The package/

62 ↗(On Diff #1279)

s/tree, check/tree. Make sure/

78 ↗(On Diff #1279)

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 ↗(On Diff #1279)

<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 ↗(On Diff #1279)

Break compound sentence:

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

169 ↗(On Diff #1279)

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

181 ↗(On Diff #1279)

Break sentences up:

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

212 ↗(On Diff #1279)

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

228 ↗(On Diff #1279)

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

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

237 ↗(On Diff #1279)

s/change/changes/

245 ↗(On Diff #1279)

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 ↗(On Diff #1279)

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

431 ↗(On Diff #1279)

Break out aside:

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

457 ↗(On Diff #1279)

s/follows/follow/

663 ↗(On Diff #1279)

s/there are/there is/

763 ↗(On Diff #1279)

s/to serial/to the serial/

789 ↗(On Diff #1279)

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 ↗(On Diff #1279)

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

826 ↗(On Diff #1279)

Break into two sentences instead of the emdash.

849 ↗(On Diff #1279)

use <acronym> tags on FTP and HTTP.

1011 ↗(On Diff #1279)

s/get/be/

1236 ↗(On Diff #1279)

Break sentence at the semicolon.

1330 ↗(On Diff #1279)

Insert "the" before CATEGORIES.

1336 ↗(On Diff #1279)

Avoid passive voice.

s/will be/is/

1377 ↗(On Diff #1279)

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

1387 ↗(On Diff #1279)

s/clearly cut/clearly defined/

1388 ↗(On Diff #1279)

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

1512 ↗(On Diff #1279)

Break sentence at semicolon.

1523 ↗(On Diff #1279)

Remove "from".

1627 ↗(On Diff #1279)

s/be added/are included/

1644 ↗(On Diff #1279)

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

1645 ↗(On Diff #1279)

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

1916 ↗(On Diff #1279)

I don't understand what this sentence is saying.

1944 ↗(On Diff #1279)

It does need the "the" before DISTFILES.

1953 ↗(On Diff #1279)

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

1964 ↗(On Diff #1279)

<acronym> tags for FTP and HTTP.

1992 ↗(On Diff #1279)

Break sentence at the emdash.

2077 ↗(On Diff #1279)

Nice!

2146 ↗(On Diff #1279)

Remove "section".

2147 ↗(On Diff #1279)

s/the port/the new port's/

2188 ↗(On Diff #1279)

Extra "with".

2243 ↗(On Diff #1279)

s/these/the/

2703 ↗(On Diff #1279)

s/for example,/like/

Should probably have <acronym> tags around GPL.

2873 ↗(On Diff #1279)

Good catch!

2893 ↗(On Diff #1279)

s/has to/have to/

3211 ↗(On Diff #1279)

s/in/is/

(Not yours, I know.)

3289 ↗(On Diff #1279)

Nice!

3308 ↗(On Diff #1279)

s/is/their/

3310 ↗(On Diff #1279)

Break at semicolon.

3311 ↗(On Diff #1279)

Remove "this"

3314 ↗(On Diff #1279)

Replace &mdash; with comma.

3410 ↗(On Diff #1279)

"using variables cleverly, only a very short"

3436 ↗(On Diff #1279)

s/Runnig/Running/

3478 ↗(On Diff #1279)

<acronym> tags on GNU.

3630 ↗(On Diff #1279)

s/can/values can/

3664 ↗(On Diff #1279)

"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 ↗(On Diff #1279)

s/in to/into/

4343 ↗(On Diff #1279)

s/all/all,/

4390 ↗(On Diff #1279)

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

4392 ↗(On Diff #1279)

s/use/Use/

4394 ↗(On Diff #1279)

"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 ↗(On Diff #1279)

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

Back to Warren. I think I got everything mostly right

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
393 ↗(On Diff #1279)

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

789 ↗(On Diff #1279)

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

1916 ↗(On Diff #1279)

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 ↗(On Diff #1279)

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

3664 ↗(On Diff #1279)

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 ↗(On Diff #1279)

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 ↗(On Diff #1279)

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 ↗(On Diff #1279)

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.

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 ↗(On Diff #1279)

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 ↗(On Diff #1279)

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.

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 ↗(On Diff #1279)

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

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
22 ↗(On Diff #1447)

design *of* the new

41 ↗(On Diff #1447)

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

220 ↗(On Diff #1447)

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

246 ↗(On Diff #1447)

Double "use".

248 ↗(On Diff #1447)

"to use" is not needed.

396 ↗(On Diff #1447)

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?

2152 ↗(On Diff #1447)

s/port/port's/

3607 ↗(On Diff #1447)

s/time/times/

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
41 ↗(On Diff #1447)

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

396 ↗(On Diff #1447)

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

wblock added a reviewer: wblock.

Please build-test and commit.

This revision is now accepted and ready to land.Sep 16 2014, 7:41 PM
mat updated this revision to Diff 1652.

Closed by commit rD45627 (authored by @mat).