Index: book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.1187
diff -u -r1.1187 book.sgml
--- book.sgml	16 May 2012 16:25:56 -0000	1.1187
+++ book.sgml	26 May 2012 20:12:52 -0000
@@ -3673,9 +3673,7 @@
 	  <filename>Makefile</filename>s and
 	  <filename>ports/Mk/bsd.*.mk</filename> and is not designed
 	  to encapsulate user-settable options &mdash; use
-	  <makevar>WITH_<replaceable>*</replaceable></makevar> and
-	  <makevar>WITHOUT_<replaceable>*</replaceable></makevar> for
-	  that purpose.</para>
+	  <makevar>PORT_OPTIONS</makevar> for that purpose.</para>
 
 	<note>
 	  <para>It is <emphasis>always</emphasis> incorrect to set any
@@ -3880,11 +3878,12 @@
 	<example>
 	  <title>Correct Declaration of an Optional Dependency</title>
 
-	  <programlisting>OPTIONS=	BAR	"Enable bar support" off
+	  <programlisting>OPTIONS_DEFINE=	BAR
+BAR_DESC=	Enable bar support
 
-.include &lt;bsd.port.pre.mk&gt;
+.include &lt;bsd.port.options.mk&gt;
 
-.if defined(WITH_BAR) && !defined(WITHOUT_BAR)
+.if ${PORTOPTIONS:MBAR}
 LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
 .endif</programlisting>
 	</example>
@@ -4207,23 +4206,19 @@
 	<sect3>
 	  <title>Background</title>
 
-	  <para>The <makevar>OPTIONS</makevar> variable gives the user
+	  <para>The <makevar>OPTIONS_*</makevar> variables give the user
 	    who installs the port a dialog with the available options
 	    and saves them to
-	    <filename>/var/db/ports/<replaceable>portname</replaceable>/options</filename>.
-	    Next time when the port has to be rebuild, the options are
-	    reused.  Never again you will have to remember all the
-	    twenty
-	    <makevar>WITH_<replaceable>*</replaceable></makevar> and
-	    <makevar>WITHOUT_<replaceable>*</replaceable></makevar>
-	    options you used to build this port!</para>
+	    <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>.
+	    Next time when the port has to be rebuilt, the options are
+	    reused.</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>.
+	    <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>.
 	    If that file does not exist, it will use the values of
-	    <makevar>OPTIONS</makevar> to create a dialog box where
+	    <makevar>OPTIONS_*</makevar> to create a dialog box 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
@@ -4242,50 +4237,126 @@
 	<sect3>
 	  <title>Syntax</title>
 
-	  <para>The syntax for the <makevar>OPTIONS</makevar> variable
-	    is:</para>
-
-	  <programlisting>OPTIONS=	OPTION	"descriptive text" default ...</programlisting>
+	  <para><makevar>OPTIONS_DEFINE</makevar> contains a list of
+	    <makevar>OPTIONS</makevar> to be used.  These are independent
+	    of each other and are not grouped:</para>
+
+	  <programlisting>OPTIONS_DEFINE=	OPT1 OPT2</programlisting>
+
+	  <para>Once defined, <makevar>OPTIONS</makevar> are
+	    optionally described:</para>
+
+	  <programlisting>OPT1_DESC=	Describe OPT1
+OPT2_DESC=	Describe OPT2
+OPT3_DESC=	Describe OPT3
+OPT4_DESC=	Describe OPT4
+OPT5_DESC=	Describe OPT5
+OPT6_DESC=	Describe OPT6</programlisting>
+
+	  <tip>
+	    <para><filename>ports/Mk/bsd.options.desc.mk</filename>
+	      has descriptions for many common
+	      <makevar>OPTIONS</makevar>; there is usually no need
+	      to override these.</para>
+	  </tip>
+
+	  <para><makevar>OPTIONS</makevar> can be grouped as radio
+	    choices (only one choice from each group allowed):</para>
+
+	  <programlisting>OPTIONS_SINGLE=		SG1
+OPTIONS_SINGLE_SG1=	OPT3 OPT4</programlisting>
+
+	  <para><makevar>OPTIONS</makevar> can also be grouped as
+	    <quote>multiple-choice</quote> lists, where
+	    <emphasis>at least one</emphasis> option must be
+	    enabled:</para>
+
+	  <programlisting>OPTIONS_MULTI=		MG1
+OPTIONS_MULTI_MG1=	OPT5 OPT6</programlisting>
+
+	  <para><makevar>OPTIONS</makevar> are unset by default,
+	    unless they are listed in
+	    <makevar>OPTIONS_DEFAULT</makevar>:</para>
 
-	  <para>The value for default is either <literal>ON</literal>
-	    or <literal>OFF</literal>.  Multiple repetitions of these
-	    three fields are allowed.</para>
+	  <programlisting>OPTIONS_DEFAULT=	OPT1 OPT3 OPT6</programlisting>
 
-	  <para><makevar>OPTIONS</makevar> definition must appear
+	  <para><makevar>OPTIONS</makevar> definitions must appear
 	    before the inclusion of
 	    <filename>bsd.port.options.mk</filename>.  The
-	    <makevar>WITH_*</makevar> and <makevar>WITHOUT_*</makevar>
-	    variables can only be tested after the inclusion of
+	    <makevar>PORT_OPTIONS</makevar> variable can only be
+	    tested after the inclusion of
 	    <filename>bsd.port.options.mk</filename>.  Inclusion of
 	    <filename>bsd.port.pre.mk</filename> can be used instead,
 	    too, and is still widely used in ports written before the
 	    introduction of <filename>bsd.port.options.mk</filename>.
 	    But be aware that some variables will not work as expected
 	    after the inclusion of
-	    <filename>bsd.port.pre.mk</filename>, typically
+	    <filename>bsd.port.pre.mk</filename>, typically some
 	    <makevar>USE_*</makevar> flags.</para>
 
 	  <example id="ports-options-simple-use">
 	    <title>Simple Use of <makevar>OPTIONS</makevar></title>
 
-	    <programlisting>OPTIONS=	FOO "Enable option foo" On \
-		BAR "Support feature bar" Off
+	    <programlisting>OPTIONS_DEFINE=	FOO BAR
+FOO_DESC=	Enable option foo
+BAR_DESC=	Support feature bar
+
+OPTIONS_DEFAULT=FOO
 
 .include &lt;bsd.port.options.mk&gt;
 
-.if defined(WITHOUT_FOO)
-CONFIGURE_ARGS+=	--without-foo
+.if ${PORT_OPTIONS:MFOO}
+CONFIGURE_ARGS+=--without-foo
 .else
-CONFIGURE_ARGS+=	--with-foo
+CONFIGURE_ARGS+=--with-foo
 .endif
 
-.if defined(WITH_BAR)
+.if ${PORT_OPTIONS:MBAR}
 RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
 .endif
 
 .include &lt;bsd.port.mk&gt;</programlisting>
 	  </example>
 
+	  <example id="ports-options-practical-use">
+	    <title>Practical Use of <makevar>OPTIONS</makevar></title>
+
+	    <programlisting>OPTIONS_DEFINE=		EXAMPLES
+
+OPTIONS_SINGLE=		BACKEND
+OPTIONS_SINGLE_BACKEND=	MYSQL PGSQL BDB
+
+OPTIONS_MULTI=		AUTH
+OPTIONS_MULTI_AUTH=	LDAP PAM SSL
+
+EXAMPLES_DESC=		Install extra examples
+MYSQL_DESC=		Use MySQL as backend
+PGSQL_DESC=		Use PostgreSQL as backend
+BDB_DESC=		Use Berkeley DB as backend
+LDAP_DESC=		Build with LDAP authentication support
+PAM_DESC=		Build with PAM support
+SSL_DESC=		Build with OpenSSL support
+
+OPTIONS_DEFAULT=	PGSQL LDAP SSL
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MPGSQL}
+USE_PGSQL=		yes
+CONFIGURE_ARGS+=	--with-postgres
+.else
+CONFIGURE_ARGS+=	--without-postgres
+.endif
+
+.if ${PORT_OPTIONS:MICU}
+LIB_DEPENDS+=	icuuc:${PORTSDIR}/devel/icu
+.endif
+
+# Check other OPTIONS
+
+.include &lt;bsd.port.mk&gt;</programlisting>
+	  </example>
+
 	  <example id="ports-options-old-style-use">
 	    <title>Old-Style Use of <makevar>OPTIONS</makevar></title>
 
@@ -4301,6 +4372,12 @@
 
 .include &lt;bsd.port.post.mk&gt;</programlisting>
 	  </example>
+
+	  <important>
+	    <para>This method of using <makevar>OPTIONS</makevar>
+	      is deprecated, and will be removed at some point.
+	      It should not be included in new ports.</para>
+	  </important>
 	</sect3>
       </sect2>
 
@@ -4317,7 +4394,7 @@
 	<example>
 	  <title>Wrong Handling of an Option</title>
 
-	  <programlisting>.if defined(WITH_FOO)
+	  <programlisting>.if ${PORT_OPTIONS:MFOO}
 LIB_DEPENDS+=		foo.0:${PORTSDIR}/devel/foo
 CONFIGURE_ARGS+=	--enable-foo
 .endif</programlisting>
@@ -4336,7 +4413,7 @@
 	<example>
 	  <title>Correct Handling of an Option</title>
 
-	  <programlisting>.if defined(WITH_FOO)
+	  <programlisting>.if ${PORT_OPTIONS:MFOO}
 LIB_DEPENDS+=		foo.0:${PORTSDIR}/devel/foo
 CONFIGURE_ARGS+=	--enable-foo
 .else
@@ -7983,7 +8060,7 @@
 
 .include &lt;bsd.port.pre.mk&gt;
 
-.if defined(WITH_WX) || ${HAVE_WX:Mwx-2.4} != ""
+.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4)
 USE_WX=			2.4
 CONFIGURE_ARGS+=	--enable-wx
 .endif</programlisting>
@@ -8000,7 +8077,7 @@
 
 .include &lt;bsd.port.pre.mk&gt;
 
-.if defined(WITH_WXPYTHON) || ${HAVE_WX:Mpython} != ""
+.if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython)
 WX_COMPS+=		python
 CONFIGURE_ARGS+=	--enable-wxpython
 .endif</programlisting>
@@ -8491,7 +8568,7 @@
 
 .include &lt;bsd.port.pre.mk&gt;
 
-.if defined(WITH_LUA5) || ${HAVE_LUA:Mlua-5.[01]} != ""
+.if defined(WITH_LUA5) || !empty(PORT_OPTIONS:MLUA5) || !empty(HAVE_LUA:Mlua-5.[01])
 USE_LUA=		5.0-5.1
 CONFIGURE_ARGS+=	--enable-lua5
 .endif</programlisting>
@@ -8508,7 +8585,7 @@
 
 .include &lt;bsd.port.pre.mk&gt;
 
-.if defined(WITH_TOLUA) || ${HAVE_LUA:Mtolua} != ""
+.if defined(WITH_TOLUA) || !empty(PORT_OPTIONS:MTOLUA) || !empty(HAVE_LUA:Mtolua)
 LUA_COMPS+=		tolua
 CONFIGURE_ARGS+=	--enable-tolua
 .endif</programlisting>
