The advice to use CFLAGS+= foo instead of CFLAGS= foo does not belong

into the developer's part, and has since been moved to the user's part.
Rewrote the section on "how to pull in variables from mk.conf", since
the word "problem" in the first sentence had bothered me over and over
again. Removed the documentation for adding "fetch" to
INTERACTIVE_STAGE, since we already have FETCH_MESSAGE for that purpose.
Added "extract" to the valid values for INTERACTIVE_STAGE, since there
might be password-protected distfiles. Now that "fetch" is excluded from
INTERACTIVE_STAGE, it is a list of _phases_ (note the misnomer here)
that are required once for every build of a package. "fetch" only needs
to be done once at all, so it is good to have these issues separated.

2 files changed, 52 insertions, 45 deletions

diff --git a/doc/guide/files/configuring.xml b/doc/guide/files/configuring.xml
index 7a9cda67baf..3c6f0e7cc68 100644
--- a/doc/guide/files/configuring.xml
+++ b/doc/guide/files/configuring.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: configuring.xml,v 1.13 2006/04/06 06:21:57 reed Exp $ -->
+<!-- $NetBSD: configuring.xml,v 1.14 2006/06/21 08:42:21 rillig Exp $ -->
 
 <chapter id="configuring">
   <title>Configuring pkgsrc</title>
@@ -92,9 +92,30 @@
     </para>
   </sect1>
 
-  <!-- Compiler settings -->
+<sect1 id="conf.compiler">
+<title>Selecting and configuring the compiler</title>
+
   <!--	PKGSRC_COMPILER -->
-  <!--	CFLAGS -->
+
+<sect2 id="conf.cflags">
+<title>Additional flags to the compiler (<varname>CFLAGS</varname>)</title>
+
+	<para>If you wish to set the <varname>CFLAGS</varname> variable,
+	please make sure to use the <literal>+=</literal> operator
+	instead of the <literal>=</literal> operator:</para>
+
+<programlisting>
+    CFLAGS+=        -your -flags
+</programlisting>
+
+	<para>Using <varname>CFLAGS=</varname> (i.e. without the
+	<quote>+</quote>) may lead to problems with packages that need
+	to add their own flags.  Also, you may want to take a look at
+	the <filename role="pkg">devel/cpuflags</filename> package if
+	you're interested in optimization for the current CPU.</para>
+
+</sect2>
+</sect1>
 
   <!-- Configuration files -->
   <!--	PKG_SYSCONFBASE -->
diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index 9039e11d024..1ceca67aa8f 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.55 2006/06/14 21:20:16 darcy Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.56 2006/06/21 08:42:21 rillig Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
   <title>Making your package work</title>
@@ -7,45 +7,31 @@
     <title>General operation</title>
 
     <sect2 id="pulling-vars-from-etc-mk.conf">
-      <title>How to pull in variables from /etc/mk.conf</title>
-
-      <para>The problem with package-defined variables that can be
-        overridden via <varname>MAKECONF</varname> or
-        <filename>/etc/mk.conf</filename> is that &man.make.1; expands a
-        variable as it is used, but evaluates preprocessor-like
-        statements (.if, .ifdef and .ifndef) as they are read.  So, to
-        use any variable (which may be set in
-        <filename>/etc/mk.conf</filename>) in one of the .if*
-        statements, the file <filename>/etc/mk.conf</filename> must be
-        included before that .if* statement.</para>
-
-      <para>Rather than having a number of ad-hoc ways of including
-        <filename>/etc/mk.conf</filename>, should it exist, or
-        <varname>MAKECONF</varname>, should it exist, include the
-        <filename>pkgsrc/mk/bsd.prefs.mk</filename> file in the package
-        Makefile before any preprocessor-like .if, .ifdef, or .ifndef
-        statements:</para>
+      <title>How to pull in user-settable variables from <filename>mk.conf</filename></title>
+
+	<para>The pkgsrc user can configure pkgsrc by overriding several
+	variables in the file pointed to by <varname>MAKECONF</varname>,
+	which is <filename>/etc/mk.conf</filename> by default. When you
+	want to use those variables in the preprocessor directives of
+	&man.make.1; (for example <literal>.if</literal> or
+	<literal>.for</literal>), you need to include the file
+	<filename>../../mk/bsd.prefs.mk</filename> before, which in turn
+	loads the user preferences.</para>
+
+	<para>But note that some variables may not be completely defined
+	after <filename>../../mk/bsd.prefs.mk</filename> has been
+	included, as they may contain references to variables that are
+	not yet defined. In shell commands this is no problem, since
+	variables are actually macros, which are only expanded when they
+	are used. But in the preprocessor directives mentioned above and
+	in dependency lines (of the form <literal>target:
+	dependencies</literal>) the variables are expanded at load
+	time.</para>
+
+	<note><para>Currently there is no exhaustive list of all
+	variables that tells you whether they can be used at load time
+	or only at run time, but it is in preparation.</para></note>
 
-<programlisting>
-    .include "../../mk/bsd.prefs.mk"
-
-    .if defined(USE_MENUS)
-    # ...
-    .endif
-</programlisting>
-
-      <para>If you wish to set the <varname>CFLAGS</varname> variable
-        in <filename>/etc/mk.conf</filename>, please make sure to use:
-
-<programlisting>
-    CFLAGS+=  -your -flags
-</programlisting>
-
-        Using <varname>CFLAGS=</varname> (i.e. without the
-        <quote>+</quote>) may lead to problems with packages that need
-        to add their own flags.  Also, you may want to take a look at
-        the <filename role="pkg">devel/cpuflags</filename> package if
-	you're interested in optimization for the current CPU.</para>
     </sect2>
 
     <sect2 id="where-to-install-documentation">
@@ -897,9 +883,9 @@ Changes to the PLIST
         in a number of ways:</para>
 
       <itemizedlist>
-        <listitem>
-          <para>help in fetching the distfiles</para>
-        </listitem>
+	<listitem>
+	  <para>When extracting the distfiles, some packages may ask for passwords.</para>
+	</listitem>
 
         <listitem>
           <para>help to configure the package before it is built</para>