From edwin@mavetju.org  Wed Jan 19 21:01:58 2005
Return-Path: <edwin@mavetju.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 2E02D16A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 19 Jan 2005 21:01:58 +0000 (GMT)
Received: from mail2out.barnet.com.au (mail2out.barnet.com.au [202.83.176.14])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 0336043D53
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 19 Jan 2005 21:01:57 +0000 (GMT)
	(envelope-from edwin@mavetju.org)
Received: by mail2out.barnet.com.au (Postfix, from userid 27)
	id 8FD48707443; Thu, 20 Jan 2005 08:01:55 +1100 (EST)
Received: from mail2-auth.barnet.com.au (mail2.barnet.com.au [202.83.176.13])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(Client CN "*.barnet.com.au", Issuer "BarNet Root Certificate Authority" (verified OK))
	by mail2.barnet.com.au (Postfix) with ESMTP id 344ED70743C
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 20 Jan 2005 08:01:55 +1100 (EST)
Received: from k7.mavetju (edwin-3.int.barnet.com.au [10.10.12.2])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(Client CN "edwin.adsl.barnet.com.au", Issuer "BarNet Root Certificate Authority" (verified OK))
	by mail2-auth.barnet.com.au (Postfix) with ESMTP id 77CCF707428
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 20 Jan 2005 08:01:54 +1100 (EST)
Received: by k7.mavetju (Postfix, from userid 1001)
	id 27DE76131; Thu, 20 Jan 2005 08:01:53 +1100 (EST)
Message-Id: <20050119210153.27DE76131@k7.mavetju>
Date: Thu, 20 Jan 2005 08:01:53 +1100 (EST)
From: Edwin Groothuis <edwin@mavetju.org>
Reply-To: Edwin Groothuis <edwin@mavetju.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] tell porters handbook about OPTIONS
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         76472
>Category:       docs
>Synopsis:       [patch] tell porters handbook about OPTIONS
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    jcamou
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jan 19 21:10:24 GMT 2005
>Closed-Date:    Wed Apr 20 23:18:16 GMT 2005
>Last-Modified:  Wed Apr 20 23:18:16 GMT 2005
>Originator:     Edwin Groothuis
>Release:        FreeBSD 5.2.1-RELEASE i386
>Organization:
-
>Environment:
System: FreeBSD k7.mavetju 5.2.1-RELEASE FreeBSD 5.2.1-RELEASE #8: Wed Dec 15 16:58:01 EST 2004 edwin@k7.mavetju:/usr/src-5.2.1/sys/i386/compile/k7 i386


>Description:

Despite being there as a feature for nearly a year now, there is
no mentioning of the OPTIONS features in the Porters Handbook.

Thanks to Florent Thoumie <flz@xbsd.org> for docbookifying it.

>How-To-Repeat:
>Fix:


--- book.sgml.old	Wed Jan 19 13:30:08 2005
+++ book.sgml	Wed Jan 19 14:21:38 2005
@@ -3538,6 +3538,84 @@
 	  </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 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
+	  is allowed.</para>
+
+	  <para>When the user runs the <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 it doesn't 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 are set.</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(WITH_FOO)
+CONFIGURE_ARGS+=	--with-foo
+.else
+CONFIGURE_ARGS+=	--without-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>Brokeness</title>
+	  <itemizedlist>
+	    <listitem>
+	      <para><command>make index</command> doesn't 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">

>Release-Note:
>Audit-Trail:

From: Edwin Groothuis <edwin@mavetju.org>
To: FreeBSD Gnats Submit <freebsd-gnats-submit@freebsd.org>
Cc:  
Subject: Re: docs/76472: [patch] tell porters handbook about OPTIONS
Date: Thu, 20 Jan 2005 08:30:44 +1100

 As noted by pav: option names should be uppercase:
 
 --- makefile-options.diff.old	Thu Jan 20 08:29:45 2005
 +++ makefile-options.diff	Thu Jan 20 08:28:43 2005
 @@ -24,7 +24,7 @@
  +	  <title>Syntax</title>
  +	  <para>The syntax for the <makevar>OPTIONS</makevar> variable is:
  +
 -+<programlisting>OPTIONS=	option	"descriptive text" default ...
 ++<programlisting>OPTIONS=	OPTION	"descriptive text" default ...
  +</programlisting>
  +
  +	  The value for default is either <literal>ON</literal> or
 @@ -48,15 +48,15 @@
  +	  <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;
  +
 -+.if defined(WITH_FOO)
 -+CONFIGURE_ARGS+=	--with-foo
 -+.else
 ++.if defined(WITHOUT_FOO)
  +CONFIGURE_ARGS+=	--without-foo
 ++.else
 ++CONFIGURE_ARGS+=	--with-foo
  +.endif
  +
  +.if defined(WITH_BAR)
 
 -- 
 Edwin Groothuis      |            Personal website: http://www.mavetju.org
 edwin@mavetju.org    |          Weblog: http://weblog.barnet.com.au/edwin/
Responsible-Changed-From-To: freebsd-doc->josef 
Responsible-Changed-By: edwin 
Responsible-Changed-When: Wed Jan 19 22:39:42 GMT 2005 
Responsible-Changed-Why:  
Josef said: 
<josef_> but if you can wait until weekend you can assign the pr to me 

http://www.freebsd.org/cgi/query-pr.cgi?pr=76472 

From: Edwin Groothuis <edwin@mavetju.org>
To: FreeBSD Gnats Submit <freebsd-gnats-submit@freebsd.org>
Cc:  
Subject: Re: docs/76472: [patch] tell porters handbook about OPTIONS
Date: Thu, 20 Jan 2005 09:39:33 +1100

 More patches, in coperation with josef@
 
 --- makefile-options.diff.old	Thu Jan 20 08:29:45 2005
 +++ makefile-options.diff	Thu Jan 20 09:35:59 2005
 @@ -24,18 +24,18 @@
  +	  <title>Syntax</title>
  +	  <para>The syntax for the <makevar>OPTIONS</makevar> variable is:
  +
 -+<programlisting>OPTIONS=	option	"descriptive text" default ...
 ++<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
 -+	  is allowed.</para>
 ++	  are allowed.</para>
  +
  +	  <para>When the user runs the <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 it doesn't exist, it will use the values of
 ++	  If that file doesn't 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 are set.</para>
 @@ -48,15 +48,15 @@
  +	  <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;
  +
 -+.if defined(WITH_FOO)
 -+CONFIGURE_ARGS+=	--with-foo
 -+.else
 ++.if defined(WITHOUT_FOO)
  +CONFIGURE_ARGS+=	--without-foo
 ++.else
 ++CONFIGURE_ARGS+=	--with-foo
  +.endif
  +
  +.if defined(WITH_BAR)
 @@ -67,7 +67,7 @@
  +	  </example>
  +
  +	<sect3>
 -+	  <title>Brokeness</title>
 ++	  <title>Brokenness</title>
  +	  <itemizedlist>
  +	    <listitem>
  +	      <para><command>make index</command> doesn't follow
 
 -- 
 Edwin Groothuis      |            Personal website: http://www.mavetju.org
 edwin@mavetju.org    |          Weblog: http://weblog.barnet.com.au/edwin/

From: Peter Pentchev <roam@ringlet.net>
To: Edwin Groothuis <edwin@mavetju.org>
Cc: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org
Subject: Re: docs/76472: [patch] tell porters handbook about OPTIONS
Date: Thu, 20 Jan 2005 10:08:11 +0200

 --H1spWtNR+x+ondvy
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On Thu, Jan 20, 2005 at 08:01:53AM +1100, Edwin Groothuis wrote:
 [snip]
 > +
 > +      <sect2>
 > +	<title><makevar>OPTIONS</makevar></title>
 
 Just a couple of minor comments; the text is great.
 
 > +
 > +	<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 have to remember all the twenty
 
 "Never again *will* you have...", perhaps?
 
 > +	  The value for default is either <literal>ON</literal> or
 > +	  <literal>OFF</literal>. Multiple repetitions of these three fields
 > +	  is allowed.</para>
 
 "Multiple repetitions... *are* allowed" sounds a bit better to me...
 
 > +	  <para>When the user runs the <command>make config</command> (or runs
 
 I don't think you need 'the' here, since 'command' is never displayed in
 the resulting text/HTML/whatever.  I'd suggest 'When the user runs
 <command>...'
 
 > +	  <command>make build</command> for the first time), the framework will
 > +	  check for
 > +	  <filename>/var/db/ports/<replaceable>portname</replaceable>/options</=
 filename>.
 > +	  If it doesn't exist, it will use the values of
 
 Maybe "If this file doesn't exist", to avoid confusion as to what the
 different 'it's mean :)
 
 > +	  <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 are set.</para>
 
 The selected variables are only set when the port is actually being
 fetched/built/installed, and not in the user environment or anything,
 right?  Maybe something like 'and the selected variables will be used
 when building the port'.
 
 [snip]
 > +	  <title>Brokeness</title>
 
 ITYM Brokenness :)
 
 Other than that, great work!
 
 G'luck,
 Peter
 
 --=20
 Peter Pentchev	roam@ringlet.net    roam@cnsys.bg    roam@FreeBSD.org
 PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
 Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
 because I didn't think of a good beginning of it.
 
 --H1spWtNR+x+ondvy
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.0 (FreeBSD)
 
 iD8DBQFB72bq7Ri2jRYZRVMRAtJiAKCMyUBXVDrkFSmMkE2/CvylcFCRCACZAZ7J
 QCRcitPhJscDPAkzYTeuhJ8=
 =3gYU
 -----END PGP SIGNATURE-----
 
 --H1spWtNR+x+ondvy--

From: "Frank Shute" <frank@esperance-linux.co.uk>
To: freebsd-doc@freebsd.org
Cc: Edwin Groothuis <edwin@mavetju.org>,
	Peter Pentchev <roam@ringlet.net>
Subject: Re: docs/76472: [patch] tell porters handbook about OPTIONS
Date: Sat, 22 Jan 2005 12:56:15 +0000

 On Thu, Jan 20, 2005 at 10:08:11AM +0200, Peter Pentchev wrote:
 >
 > On Thu, Jan 20, 2005 at 08:01:53AM +1100, Edwin Groothuis wrote:
 > [snip]
 > > +
 > > +      <sect2>
 > > +	<title><makevar>OPTIONS</makevar></title>
 > 
 > Just a couple of minor comments; the text is great.
 > 
 > > +
 > > +	<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 have to remember all the twenty
 
 My take on the 2nd to last sentence:
 
 "When the port has to be rebuilt, the options are reused."
                                ^
 > 
 > "Never again *will* you have...", perhaps?
 
 Agreed along with your other comments.
 
 [snip]
 
 -- 
 
  Frank 
 
 
 print "f r a n k @ e s p e r a n c e - l i n u x . c o . u k" | sed 's/ //g'
 
                       --->PGP keyID: 0x10BD6F4B<---                          
Responsible-Changed-From-To: josef->docs 
Responsible-Changed-By: edwin 
Responsible-Changed-When: Tue Mar 15 23:00:43 GMT 2005 
Responsible-Changed-Why:  
Take away from Joseph since he's busy playing records :-) 

http://www.freebsd.org/cgi/query-pr.cgi?pr=76472 
Responsible-Changed-From-To: docs->freebsd-doc 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Tue Mar 15 23:18:01 GMT 2005 
Responsible-Changed-Why:  
Canonicalize assignment. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=76472 
Responsible-Changed-From-To: freebsd-doc->jcamou  
Responsible-Changed-By: jcamou 
Responsible-Changed-When: Wed Apr 20 19:29:09 GMT 2005 
Responsible-Changed-Why:  
Take it, I'll work on it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=76472 

From: "Jesus R. Camou" <jcamou@FreeBSD.org>
To: freebsd-gnats-submit@FreeBSD.org
Cc: edwin@mavetju.org, roam@FreeBSD.org, josef@FreeBSD.org
Subject: Re: docs/76472: [patch] tell porters handbook about OPTIONS
Date: Wed, 20 Apr 2005 13:04:34 -0700

 --QNDPHrPUIc00TOLW
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 
 How about the following patch?
 
 -- 
 Jesus R. Camou - jcamou@FreeBSD.org
 
 
 --QNDPHrPUIc00TOLW
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename="book.diff"
 
 Index: book.sgml
 ===================================================================
 RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
 retrieving revision 1.549
 diff -u -r1.549 book.sgml
 --- book.sgml	3 Apr 2005 08:20:53 -0000	1.549
 +++ book.sgml	20 Apr 2005 19:57:26 -0000
 @@ -3539,6 +3539,84 @@
  	  </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> doesn't 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">
 
 --QNDPHrPUIc00TOLW--

From: Edwin Groothuis <edwin@mavetju.org>
To: "Jesus R. Camou" <jcamou@FreeBSD.org>
Cc: freebsd-gnats-submit@FreeBSD.org, roam@FreeBSD.org,
	josef@FreeBSD.org
Subject: Re: docs/76472: [patch] tell porters handbook about OPTIONS
Date: Thu, 21 Apr 2005 08:34:43 +1000

 On Wed, Apr 20, 2005 at 01:04:34PM -0700, Jesus R. Camou wrote:
 > How about the following patch?
 
 excellenet. Get it in!
 
 Edwin
 
 -- 
 Edwin Groothuis      |            Personal website: http://www.mavetju.org
 edwin@mavetju.org    |          Weblog: http://weblog.barnet.com.au/edwin/
State-Changed-From-To: open->closed  
State-Changed-By: jcamou 
State-Changed-When: Wed Apr 20 23:16:15 GMT 2005 
State-Changed-Why:  
Patch committed with some changes, thanks edwin and all 
of you that reviewed the patch.  

http://www.freebsd.org/cgi/query-pr.cgi?pr=76472 
>Unformatted:
