svn commit: r51378 - head/en_US.ISO8859-1/books/porters-handbook/flavors

[Mathieu Arnold]

Author: mat
Date: Tue Jan  9 13:06:54 2018
New Revision: 51378
URL: https://svnweb.freebsd.org/changeset/doc/51378

Log:
  Enhance the flavors chapter with the experience from the past few weeks.
  
  Sponsored by:	Absolight

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml	Tue Jan  9 02:28:43 2018	(r51377)
+++ head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml	Tue Jan  9 13:06:54 2018	(r51378)
@@ -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