Include the use of the OPTIONS features in

the Porters Handbook.

PR:		docs/76472
Submitted by:	edwin
Reviewed by:	roam
Approved by:	trhodes (mentor)

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -3543,6 +3543,84 @@ PATCHFILES=     patch1:test</programlisting>
 	  </table>
 
       </sect2>
+
+      <sect2>
+	<title><makevar>OPTIONS</makevar></title>
+
+	<sect3>
+	  <title>Background</title>
+	    <para>The <makevar>OPTIONS</makevar> variable gives the user who
+	      installs the port a dialog with the available options and saves
+	      them to <filename>/var/db/ports/portname/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>
+	</sect3>
+
+	<sect3>
+	  <title>Syntax</title>
+	    <para>The syntax for the <makevar>OPTIONS</makevar> variable is:
+
+<programlisting>OPTIONS=	OPTION	"descriptive text" default ...
+</programlisting>
+
+	      The value for default is either <literal>ON</literal> or
+	      <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>
+
+	<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
+
+.include &lt;bsd.port.pre.mk&gt;
+
+.if defined(WITHOUT_FOO)
+CONFIGURE_ARGS+=	--without-foo
+.else
+CONFIGURE_ARGS+=	--witht-foo
+.endif
+
+.if defined(WITH_BAR)
+RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
+.endif
+
+.include &lt;bsd.port.post.mk&gt;</programlisting></para>
+	  </example>
+
+	<sect3>
+	  <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>
+	    </listitem>
+	  </itemizedlist>
+	</sect3>
+	
+      </sect2>
+
     </sect1>
 
     <sect1 id="makefile-wrkdir">