Add a Flavors chapter.
Needs ReviewPublic

Authored by mat on Nov 27 2017, 4:50 PM.

Details

Reviewers
brd
wblock
Group Reviewers
portmgr

Diff Detail

Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 13165
Build 13411: arc lint + arc unit
mat created this revision.Nov 27 2017, 4:50 PM
bcr added a subscriber: bcr.Nov 28 2017, 8:50 AM

Two suggestions...

en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
21

I would put this single-sentence paragraph into the previous one.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
3631

Maybe having a link to the flavors chapter here as well is a good idea?

mat marked an inline comment as done.Nov 28 2017, 3:44 PM
mat added inline comments.
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
3631

Mmm, I don't know, there is already a link in the USE_PYTHON=flavors entry.

mat updated this revision to Diff 35924.Nov 28 2017, 3:44 PM
  • Small fixes.
  • Some extra bits.
mat updated this revision to Diff 35925.Nov 28 2017, 3:50 PM
  • example for helpers.
bcr added a comment.Nov 28 2017, 4:01 PM

I'd wait until the other two reviewers had time to review. I myself don't have anything else. Thanks for the work on this!

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
3631

Ah, OK. That's fine then.

mat updated this revision to Diff 35960.Nov 29 2017, 4:12 PM
  • Add another, bigger, example, and some other fixes.
emaste added a subscriber: emaste.Nov 30 2017, 1:59 PM
emaste added inline comments.
en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
19

Maybe comment briefly on what a "normal" and "lite" option means - perhaps something like "a normal version, and a lite version with fewer features and dependencies."

94–104

This paragraph is confusing to me

adamw added a subscriber: adamw.Nov 30 2017, 4:45 PM
adamw added inline comments.
en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
31

I'd reinforce this:

To distinguish flavors from options, which are always uppercase letters, f[lavor names can <emphasis>only</emphasis> contain...]

94–104

I agree. I'd simplify it like this:

To guard against <varname>FLAVOR</varname> being empty, which would cause a &man.make.1 error, use <literal>${FLAVOR:U}</literal> in string comparisons instead of <literal>${FLAVOR}</literal>.

145

Add "the"

To make the <filename>Makefile</filename>

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
3666

s/one/version/

adamw added inline comments.Nov 30 2017, 4:47 PM
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
3666

And s/have//.

mat marked 10 inline comments as done.Dec 1 2017, 9:15 AM
wblock added inline comments.Dec 8 2017, 8:23 PM
en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
18

This is redundant.

<emphasis>Flavors</emphasis> provide a way to have more than one variation of a
port installed at the same time.
19
port can have a normal version with standard options, and a <quote>lite</quote>
version with fewer options and features so it is smaller in size.

Is this a good example? I mean, it seems like the typical use of flavors is to have more than one variant of a port installed at the same time. Like having (sigh) py27-setuptools, py34-setuptools, and py36-setuptools.

23

I would not make Flavors all uppercase here. The title is about using the feature, not the make variable. I think.

If it really is about the make variable, be explicit about that:

<title>Using the <varname>FLAVORS</varname> Variable</title>
31

Good, but flip it so the restrictions are first and then the reason.

<para>Flavor names are <emphasis>only</emphasis> allowed to contain
33
<literal>_</literal>.  This makes them visibly different from the values for options, which are upper case only.</para>
94–104

FLAVOR must have a defined value before flavor-specific processing can start. Using the <literal>:U</literal> &man.make.1; feature simplifies this. If the variable is empty, the value it is compared to is assigned to it.

(I'm not certain if this is a correct explanation.)

en_US.ISO8859-1/books/porters-handbook/order/chapter.xml
381

s/with/by/

382

Not sure if Flavors needs to be capitalized here. I would also move the <xref to the next line so that the whole tag is on one line:

Continue with the possible flavors helpers.  See
<xref linkend="flavors-using"/> for more
information.</para>
383

And I'm positive that Information should not be capitalized here.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
3630
defined.  It also implies
3668

s/Only/This is only/

3732

Typo: s/conditionnal/conditional/

3739

Typo: s/conditionnal/conditional/

3746

Typo: s/conditionnal/conditional/

3753

Typo: s/conditionnal/conditional/

3760

Typo: s/conditionnal/conditional/