Improve MASTER_SITES section.

[mat]

Summary

Try to make things more readable by putting normal variables and magic ones in
separate sections. (maybe)
Update the magic list.
Add a tip about the variables saying again what was just said in the hope that
it would be read.

[mat]

I have not reindented the content of the new <sect3> to keep the diff readable, I'll do it in another commit.

[wblock]

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

1645–1646

s/possible refer/possible to refer/

End sentence after "form". See next comment for a suggestion.

1645–1646

Use serial comma after GNU.

MASTER_SITES can be set to numerous predefined macros such as SF, GNU, or CPAN.

1645–1646

s/may/might/ ("may" is generally for permission instead of possibility)

[mat]

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

1645–1646

I'd be tempted to write "should" here. "might" implies that the possibility is not very likely to occur, right ?

[mat]

Comments from wblock.

[wblock]

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

1645–1646

"Should" should only be used for a recommendation: "Only zzxx should be used." It's bad to use "should" to indicate unsureness: "This should work." (That raises questions for the reader: "what if it doesn't?")
"might" is better for indicating possibility. So:

may: permission
might: possibility
should: recommendation

Probably the best approach here is to rewrite the sentence to say what it was trying to say, that there are predefined macros available for the most common MASTER_SITE_* values. It also needs a pointer to where the reader can look to see if the one they need is already defined.

[mat]

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

1645–1646

I don't remember, is there a way to link to a file in one of our svn repositories ? or should I put a link to svnweb.freebsd.org/... ?

[mat]

Update a bit, add a link to the current bsd.sites.mk file.

[wblock]

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

1651

No comma after CPAN.

1652

"such as" is redundant with the earlier use in the same sentence. Use "like". Or consider rewording the sentence to be shorter:

Predefined variables are available for popular archives like SourceForge (SF), GNU (GNU), or CPAN (CPAN). MASTER_SITES can use these values directly:

1658–1659

If there really is not any reason to use the old format, why not just remove that example?

1665–1666

No whitespace between the <link> tag and the content:

...markup"><filename>Mk/bsd.sites.mk...

1665–1666

I was thinking of just a filename here (See Mk/bsd.sites.mk), but the link to svnweb is probably at least as good.

1666

s/There are new entries added all the time/New entries are added often/

1701

I say that it's a mistake to include wrong examples, better just to show the right way only. Somebody is going to use that because "it was in the book". Not everyone agrees.

1704

s/needs to be used/is needed/

1708

Again, I suggest not showing the wrong way.

[mat]

Update.

[mat]

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

1652

Yeah, but then it's beginning to have less and less sense.

There are variables defined, like MASTER_SITE_SF or MASTER_SITE_PERL_CPAN and there are macros that can be used, like SOURCEFORGE or PERL_CPAN (and their abbreviation, SF and CPAN), and while people can use the variables if they really need to, they should use the abbreviated macros.

1658–1659

So that when people stumble upon a Makefile written in the old format, they know how to modernize it ?

1665–1666

Well, it was already here before, so I assumed you meant a real link to it.

[wblock]

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

1652

Sorry, "variables" was not meant to be literal. Your response above seems like a good way to explain it, how about going with that?

1658–1659

Ah, then that is how it should be explained, as opposed to "this also works, but don't use it".

1708

But as above, explain that this is the old format. And possibly suggest fixing it. "New ports or ports that are being updated should use the new format shown above."

[mat]

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

1652

Well, I don't think there's a need for the handbook to go into all those details, but if variables is not meant to be litteral, then, well, I don't know. Is the current paragraph good enough ?

[mat]

Update a bit.

[wblock]

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

1652

I would prefer it to be simpler and shorter, something like:

Shortcut abbreviations are available for popular archives like SourceForge (<literal>SF</literal>), GNU (<literal>GNU</literal>), or Perl CPAN (<literal>CPAN</literal>). <varname>MASTER_SITES</varname> can use them directly:

(The "here is an example" sentence can be left out.)

[wblock]

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

1659–1661

"Can still be used" sounds like it is giving permission, so:

s/can still be used/still works/

[mat]

With wblock's remarks.

[wblock]

Please remember to check with igor, build-test, and add the Approved-by: wblock (mentor).

[mat]

Closed by commit rD46445 (authored by @mat).