Add more information about running 'make describe' and portlint to

the Testing section.

Reviewed by:	marcus, eik, others
Approved by:	ceri (mentor)

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

@@ -4891,14 +4891,72 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
   <chapter id="testing">
     <title>Testing your port</title>
 
+      <sect1 id="make-describe">
+	<title>Running <command>make describe</command></title>
+
+	<para>Several of the &os; port maintainance tools, such as
+	  &man.portupgrade.1;, rely on a database called
+	  <filename>/usr/ports/INDEX</filename> which keeps track of such
+	  items as port dependencies.  <filename>INDEX</filename> is created
+	  by the top-level <filename>ports/Makefile</filename> via
+	  <command>make index</command>, which descends into each
+	  port subdirectory and executes <command>make describe</command>
+	  there.  Thus, if <command>make describe</command> fails in any
+	  port, no one can generate <filename>INDEX</filename>, and many
+	  people will quickly become unhappy.</para>
+
+	<note>
+	  <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>
+	</note>
+
+	<example id="dot-error-breaks-index"><title></title>
+	  <para>Assume that someone has the line 
+	    <programlisting>USE_POINTYHAT=yes</programlisting>
+	    in <filename>make.conf</filename>.  The first of
+	    the next two <filename>Makefile</filename> snippets will
+	    cause <command>make index</command> to fail, while the
+	    second one will not:
+	    <programlisting>.if USE_POINTYHAT
+.error "POINTYHAT is not supported"
+.endif</programlisting>
+	    <programlisting>.if USE_POINTYHAT
+IGNORE=POINTYHAT is not supported
+.endif</programlisting>
+	  </para>
+	</example>
+
+	<para>If <command>make describe</command> produces a string
+	  rather than an error message, you are probably safe.  See
+	  <filename>bsd.port.mk</filename> for the meaning of the
+	  string produced.</para>
+
+	<para>Also note that running a recent version of
+	  <command>portlint</command> (as specified in the next section)
+	  will cause <command>make describe</command> to be run
+	  automatically.</para>
+      </sect1>
+
       <sect1 id="testing-portlint">
 	<title>Portlint</title>
 
 	<para>Do check your work with <link
 	    linkend="porting-portlint"><command>portlint</command></link>
-	  before you submit or commit it.</para>
-      </sect1>
+	  before you submit or commit it.  <command>portlint</command>
+	  warns you about many common errors, both functional and
+	  stylistic.  For a new (or repocopied) port,
+	  <command>portlint -A</command> is the most thorough; for an
+	  existing port, <command>portlint -C</command> is sufficient.</para>
 
+	<para>Since <command>portlint</command> uses heuristics to
+	  try to figure out errors, it can produce false positive
+	  warnings.  In addition, occasionally something that is
+	  flagged as a problem really cannot be done in any other
+	  way due to limitations in the ports framework.  When in
+	  doubt, the best thing to do is ask on &a.ports;.</para>
+      </sect1>
 
       <sect1 id="porting-prefix">
 	<title><makevar>PREFIX</makevar></title>