Add documentation about opt_VARS from D3410.

[mat]

• minor wording.

[mat]

• search/replace errors.

[wblock]

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

4503 ↗

(On Diff #8294)

"Check in this chapter" is a little confusing. Maybe state this as more of a warning.

These provide a generic way of setting variables.  Before using them, see if there is already a specific helper available in <xref ...>

4506 ↗

(On Diff #8294)

This sentence is long, has lots of if/thens, and is hard to interpret. It can be simplified with some rearrangement. I think both key and value should be lowercase to avoid implying they are literal.

When option OPT is selected, and OPT_VARS is defined,
key is set to value for each for each key=value pair in OPT_VARS.

4519 ↗

(On Diff #8294)

This sentence is similarly confusing. Is it just a repeat of the one above, but with "+=" instead of just "="? If so, it can be simplified because the information already given does not need to be repeated.

When option OPT is selected, and OPT_VARS defined,
key=value and key+=value pairs are evaluated from OPT_VARS.
An = causes the existing value to be overwritten, while a += appends the value.

4524 ↗

(On Diff #8294)

Please use something other than the same name in lowercase to indicate values. It's hard to tell what OPT1 and opt1 mean or how they are different.

4555 ↗

(On Diff #8294)

The same notes as above apply to this section, which is mostly a copy of the section above. Maybe they can be combined?

[mat]

• Combine both sections, and rewrite based on wblock's comments.

[mat]

• Combine other X/X_OFF helper sections.

[mat]

I will commit the addition of opt_VARS and the merge of the sections in two different commits, I'm just having one review for all 0:-)

[mat]

• Merge a few other on/off helpers.

[mat]

• fix straggling tag.

[wblock]

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

4118 ↗

(On Diff #8489)

"selected" is a little confusing. It means (I think) when the user has enabled that option. Is "enabled" better?

4130 ↗

(On Diff #8489)

Maybe add <emphasis> tags to "not"?

4245 ↗

(On Diff #8489)

As above, emphasizing "not" makes this a little clearer.

[mat]

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

4118 ↗

(On Diff #8489)

No, enabled is not better, it's going to confuse people with all the opt_CONFIGURE_ENABLE stuff, so I keep using selected everywhere.

[mat]

Add emphasis around the not selected bits.

[wblock]

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

4118 ↗

(On Diff #8548)

It's just that "selected" can be taken to mean "chosen" here. Maybe "set by the user"?

[mat]

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

4118 ↗

(On Diff #8548)

I'm not sure what would be wrong with chosen. "set by the user" would end up being too long, I feel.

[wblock]

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

4118 ↗

(On Diff #8548)

"Chosen" is ambiguous because a user can "choose" an option by scrolling up and down to it, but that does not necessarily mean they enabled it or disabled it. Likewise with "selected", it is possible to select an option without that meaning it is enabled or disabled. Even "set" has problems, because an option can be "set" to disabled. There might not be a good way to do this.

[mat]

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

4118 ↗

(On Diff #8548)

I see what you mean. I doubt anybody will ever think that highlighting the option and not putting the little ✔️ in the box in front of it will mean it's been selected.