From 9d8ee0511113119456677108c1b59056ff1d59c2 Mon Sep 17 00:00:00 2001
From: Pav Lucistnik <pav@FreeBSD.org>
Date: Fri, 30 Sep 2005 07:58:34 +0000
Subject: [PATCH] OPTIONS handling: - move two paras about user side of this
 feature to the "background" part   of the text - document two critical quirks
 - fix indentation in the example - refresh bugs part

---
 .../books/porters-handbook/book.sgml          | 48 +++++++++++--------
 1 file changed, 28 insertions(+), 20 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index 8ca69b8e54..a91f3d882a 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -3698,6 +3698,20 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 	      <makevar>WITH_<replaceable>*</replaceable></makevar> and
 	      <makevar>WITHOUT_<replaceable>*</replaceable></makevar> options you
 	      used to build this port!</para>
+
+	    <para>When the user runs <command>make config</command> (or runs
+	      <command>make build</command> for the first time), the framework will
+	      check for
+	      <filename>/var/db/ports/<replaceable>portname</replaceable>/options</filename>.
+	      If that file does not exist, it will use the values of
+	      <makevar>OPTIONS</makevar> to create a dialogbox where the options
+	      can be enabled or disabled.  Then the
+	      <filename>options</filename> file is saved and the selected
+	      variables will be used when building the port.</para>
+
+	    <para>Use <command>make showconfig</command> to see the saved
+	      configuration.  Use <command>make rmconfig</command> to remove the
+	      saved configuration.</para>
 	</sect3>
 
 	<sect3>
@@ -3711,25 +3725,23 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 	      <literal>OFF</literal>.  Multiple repetitions of these three fields
 	      are allowed.</para>
 
-	    <para>When the user runs <command>make config</command> (or runs
-	      <command>make build</command> for the first time), the framework will
-	      check for <filename>/var/db/ports/<replaceable>portname</replaceable>
-	      /options</filename>.
-	      If that file does not exist, it will use the values of
-	      <makevar>OPTIONS</makevar> to create a dialogbox where the options
-	      can be enabled or disabled.  Then the options file is saved and the
-	      selected variables will be used when building the port.</para>
-
-	    <para>Use <command>make showconfig</command> to see the saved
-	      configuration.  Use <command>make rmconfig</command> to remove the
-	      saved configuration.</para>
+	    <para><makevar>OPTIONS</makevar> definition must appear before
+	      the inclusion of <filename>bsd.port.pre.mk</filename>.
+	      The <makevar>WITH_*</makevar> and <makevar>WITHOUT_*</makevar>
+	      variables can only be tested after the inclusion of
+	      <filename>bsd.port.pre.mk</filename>.  Due to a deficiency
+	      in the infrastructure, you can only test
+	      <makevar>WITH_*</makevar> variables for options, which are
+	      <literal>ON</literal> by default, and
+	      <makevar>WITHOUT_*</makevar> variables for options, which
+	      defaults to <literal>OFF</literal>.</para>
 
 	<sect3>
 	  <title>Example</title>
 	  <example id="ports-options-simple-use">
 	    <title>Simple use of <makevar>OPTIONS</makevar></title>
-	    <para><programlisting>OPTIONS=	FOO "Enable option foo" On \
-			BAR "Support feature bar" Off
+	    <para><programlisting>OPTIONS=      FOO "Enable option foo" On \
+              BAR "Support feature bar" Off
 
 .include &lt;bsd.port.pre.mk&gt;
 
@@ -3750,12 +3762,8 @@ RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
 	  <title>Brokenness</title>
 	  <itemizedlist>
 	    <listitem>
-	      <para><command>make index</command> does not follow
-	      <makevar>OPTIONS</makevar> yet (ports/75727)</para>
-	    </listitem>
-	    <listitem>
-	      <para><makevar>PACKAGE_BUILDING</makevar> is ignoring
-	      <makevar>OPTIONS</makevar> (ports/75727?)</para>
+	      <para><makevar>OPTIONS</makevar> are ignored in
+		<makevar>BATCH</makevar> mode.</para>
 	    </listitem>
 	  </itemizedlist>
 	</sect3>