Improved the wording in the INTERACTIVE_STAGE explanation and general

notes about using variables at load time.

1 files changed, 20 insertions, 29 deletions

diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index 19fa77a5ba8..51b2d11ef35 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.135 2016/06/11 13:06:14 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.136 2016/06/11 13:12:38 rillig Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
 <title>Making your package work</title>
@@ -6,15 +6,11 @@
 <sect1 id="general-operation">
   <title>General operation</title>
 
-  <sect2 id="portability-of-packages">
-    <title>Portability of packages</title>
-
-    <para>One appealing feature of pkgsrc is that it runs on many
-    different platforms. As a result, it is important to ensure,
-    where possible, that packages in pkgsrc are portable. This
-    chapter mentions some particular details you should pay
-    attention to while working on pkgsrc.</para>
-  </sect2>
+  <para>One appealing feature of pkgsrc is that it runs on many
+  different platforms. As a result, it is important to ensure,
+  where possible, that packages in pkgsrc are portable. This
+  chapter mentions some particular details you should pay
+  attention to while working on pkgsrc.</para>
 
   <sect2 id="pulling-vars-from-etc-mk.conf">
     <title>How to pull in user-settable variables from &mk.conf;</title>
@@ -31,16 +27,17 @@
     <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:
+    not yet defined. In shell commands (the lines in
+    <filename>Makefile</filename> that are indented with a tab) this
+    is no problem, since variables 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>
+    <note><para>To check whether a variable can be used at load time,
+    run <command>pkglint -Wall</command> on your package.</para></note>
+
   </sect2>
 
   <sect2 id="user-interaction">
@@ -75,23 +72,17 @@
       </listitem>
     </itemizedlist>
 
-    <para>The <varname>INTERACTIVE_STAGE</varname> definition is
-    provided to notify the pkgsrc mechanism of an interactive stage
-    which will be needed, and this should be set in the package's
-    <filename>Makefile</filename>, e.g.:</para>
-
-    <programlisting>
-INTERACTIVE_STAGE=      build
-    </programlisting>
-
-    <para>Multiple interactive stages can be specified:</para>
+    <para>A package can set the <varname>INTERACTIVE_STAGE</varname>
+    variable to define which stages need interaction. This should be
+    done in the package's <filename>Makefile</filename>, e.g.:</para>
 
     <programlisting>
 INTERACTIVE_STAGE=      configure install
     </programlisting>
 
     <para>The user can then decide to skip this package by setting the
-    <varname>BATCH</varname> variable.</para>
+    <varname>BATCH</varname> variable. Packages that require interaction
+    are also excluded from bulk builds.</para>
   </sect2>
 
   <sect2 id="handling-licenses">
@@ -122,7 +113,7 @@ INTERACTIVE_STAGE=      configure install
     this is a bug.)</para>
 
     <para>One might want to only install packages with a BSD license,
-    or the GPL, and not the other.  The free licenses are added to the 
+    or the GPL, and not the other.  The free licenses are added to the
     default <varname>ACCEPTABLE_LICENSES</varname> variable.  The
     user can override the default by setting the
     <varname>ACCEPTABLE_LICENSES</varname> variable with "=" instead