From 86821e0c2f51a6bef9cc0f7c8614d144c6205144 Mon Sep 17 00:00:00 2001
From: Mathieu Arnold <mat@FreeBSD.org>
Date: Tue, 9 Jan 2018 13:06:54 +0000
Subject: [PATCH] Enhance the flavors chapter with the experience from the past
 few weeks.

Sponsored by:	Absolight
---
 .../porters-handbook/flavors/chapter.xml      | 33 ++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
index a8d0497c1c..0f5fbe12c1 100644
--- a/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
@@ -29,6 +29,14 @@
       The first flavor in <varname>FLAVORS</varname> is the default
       flavor.</para>
 
+    <tip>
+      <para>It can help simplify the logic of the
+	<filename>Makefile</filename> to also define
+	<varname>FLAVOR</varname> as:</para>
+
+      <programlisting>FLAVOR?=	${FLAVORS:[1]}</programlisting>
+    </tip>
+
     <important>
       <para>To distinguish flavors from options, which are always
 	uppercase letters, flavor names can <emphasis>only</emphasis>
@@ -43,15 +51,38 @@
 	port can be removed, and the port can be converted to flavors
 	with:</para>
 
-      <programlisting>FLAVORS=	normal lite
+      <programlisting>FLAVORS=	default lite
 lite_PKGNAMESUFFIX=	-lite
 [...]
 .if ${FLAVOR:U} != lite
 [enable non lite features]
 .endif</programlisting>
+
+      <note>
+	<para>The first flavor is the default one, and is called,
+	  here, <literal>default</literal>.  It is not an obligation,
+	  and if possible, use a more specific flavor name, like in
+	  <xref linkend="flavors-using-ex2"/>.</para>
+      </note>
     </example>
 
     <example xml:id="flavors-using-ex2">
+      <title>Another Basic Flavors Usage</title>
+
+      <para>If a port has a <literal>-nox11</literal> slave port, the
+	slave port can be removed, and the port can be converted to
+	flavors with:</para>
+
+      <programlisting>FLAVORS=	x11 nox11
+FLAVOR?=	${FLAVORS:[1]}
+nox11_PKGNAMESUFFIX=	-nox11
+[...]
+.if ${FLAVOR} = x11
+[enable x11 features]
+.endif</programlisting>
+    </example>
+
+    <example xml:id="flavors-using-ex3">
       <title>More Complex Flavors Usage</title>
 
       <para>Here is a slightly edited excerpt of what is present in