Add a section describing automatic dependencies, the problems they

cause, and the correct approach.  Patch is a modified version of the
original in the PR.

PR:		docs/166855
Submitted by:	A.J. Kehoe IV

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

@@ -3843,6 +3843,56 @@ ALWAYS_KEEP_DISTFILES=	yes
 	  may be able to save a large number of people—including
 	  yourself&mdash; a lot of grief in the process.</para>
       </sect2>
+
+      <sect2>
+	<title>Problems Caused by Automatic Dependencies</title>
+
+	<para>Dependencies must be declared either explicitly or by
+	  using the <link
+	    linkend="makefile-options">OPTIONS framework</link>.
+	  Using other methods like automatic detection complicates
+	  indexing, which causes problems for port and package
+	  management.</para>
+
+	<example>
+	  <title>Wrong Declaration of an Optional Dependency</title>
+
+	  <programlisting>.include &lt;bsd.port.pre.mk&gt;
+
+.if exists(${LOCALBASE}/bin/foo)
+LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
+.endif</programlisting>
+	</example>
+
+	<para>The problem with trying to automatically add
+	  dependencies is that files and settings outside an
+	  individual port can change at any time.  For example: an
+	  index is built, then a batch of ports are installed.  But
+	  one of the ports installs the tested file.  The index is now
+	  incorrect, because an installed port unexpectedly has a new
+	  dependency.  The index may still be wrong even after
+	  rebuilding if other ports also determine their need for
+	  dependencies based on the existence of other files.</para>
+
+	<example>
+	  <title>Correct Declaration of an Optional Dependency</title>
+
+	  <programlisting>OPTIONS=	BAR	"Enable bar support" off
+
+.include &lt;bsd.port.pre.mk&gt;
+
+.if defined(WITH_BAR) && !defined(WITHOUT_BAR)
+LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
+.endif</programlisting>
+	</example>
+
+	<para>Testing option variables is the correct method.  It will
+	  not cause inconsistencies in the index of a batch of ports,
+	  provided the options were defined prior to the index build.
+	  Simple scripts can then be used to automate the building,
+	  installation, and updating of these ports and their
+	  packages.</para>
+      </sect2>
     </sect1>
 
     <sect1 id="makefile-masterdir">