diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index c51319ecac..9fee1a1eda 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -6207,7 +6207,8 @@ as .putsy.conf and edit it.</programlisting>
 	  <para>It is important to be able to generate this file no
 	  matter what options are present in <filename>make.conf</filename>,
 	  so please avoid doing things such as using <literal>.error</literal>
-	  statements when (for instance) a dependency is not satisfied.</para>
+	  statements when (for instance) a dependency is not satisfied.
+	  (See <xref linkend="dads-dot-error">.)</para>
 	</note>
 
 	<example id="dot-error-breaks-index">
@@ -9378,6 +9379,26 @@ bacula:*:910:</programlisting>
 	  interested committers a little time to fix the problems.</para>
       </sect1>
 
+      <sect1 id="dads-dot-error">
+	<title>Avoid use of the <literal>.error</literal> construct</title>
+
+	<para>The correct way for a <filename>Makefile</filename> to
+	  signal that the port can not be installed due to some external
+	  factor (for instance, the user has specified an illegal
+	  combination of build options) is to set a nonblank value to
+	  <makevar>IGNORE</makevar>.  This value will be formatted and
+	  shown to the user by <command>make install</command>.</para>
+
+	<para>It is a common mistake to use <literal>.error</literal>
+	  for this purpose.  The problem with this is that many
+	  automated tools that work with the ports tree will fail in
+	  this situation.  The most common occurence of this is seen
+	  when trying to build <filename>/usr/ports/INDEX</filename>
+	  (see <xref linkend="make-describe">).  However, even more
+	  trivial commands such as <command>make -V maintainer</command>
+	  also fail in this scenario.  This is not acceptable.</para>
+      </sect1>
+
       <sect1 id="dads-workarounds">
 	<title>Necessary workarounds</title>