ports.7: Add an example of how to use flavors

[0mp]

Summary

ports.7: Add an example of how to use flavors

At the moment the manual page is not documenting how to build a flavored
package. Let's start documenting flavors with an example of a typical use
case.

Requested by:		cem, dim

[bcr]

Small nit, the rest is fine. Thanks for adding the example, I think it is really useful to have.

share/man/man7/ports.7

608 ↗

(On Diff #54900)

s/examples/example/

[mat]

share/man/man7/ports.7

614 ↗

(On Diff #54900)

Looking at how FLAVOR is passed to sub-makes in bsd.port.mk, I wonder if it should not be:

env FLAVOR=py37 make build

[0mp]

• While here, fix a typo in example 2.
• Fix other typos.
• Use env(1) as suggested by @mat. As we can see in bsd.port.mk, it's better to pass FLAVOR via the environment:

1049  # Disallow forced FLAVOR as make argument since we cannot change it to the
1050  # proper default.
1051  .if empty(FLAVOR) && !empty(.MAKEOVERRIDES:MFLAVOR)
1052  .error FLAVOR may not be passed empty as a make argument.
1053  .endif

[cem]

Thanks for doing this, I really appreciate it!

share/man/man7/ports.7

608–609 ↗

(On Diff #54907)

1. Doc style suggestion: split it into two sentences. We prefer direct, simple sentences in manuals instead of complex ones, when possible.

For example, "The following command …. of a port. (In this case... support.)"

2. Don't use .Po, .No, or .Pc macros. Just use normal parentheses directly. Stylized text goes on its own line, and ordinary text on a following line. E.g.,:

(In this case,
.Pa www/py-django
is going to be built with Python 3.7 support.)

[0mp]

• Avoid Po, Pc & No macros
• Simplify sentences

[0mp]

Thank you @bcr, @cem & @mat for your suggestions :)

[matthew]

share/man/man7/ports.7

610 ↗

(On Diff #54915)

www/py-django was deprecated and then undeprecated last week -- it's quite likely that it will disappear in the relatively near future. Maybe choose a different example port?

[0mp]

Use devel/py-pip instead of www/py-django, as it is a much more stable Python port.

[cem]

Looks good to me. Thank you!