RFC: minor change to Porter's Handbook

[Mark Linimon]

I'd like to expand on the Testing Your Port section by expanding
the section on portlint(1) and adding a section on 'make describe'.
Would anyone have any objections to the following:

Index: book.sgml
===================================================================
RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.404
diff -u -r1.404 book.sgml
--- book.sgml	19 May 2004 18:01:05 -0000	1.404
+++ book.sgml	22 May 2004 18:33:47 -0000
@@ -4891,14 +4891,71 @@
   <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 maintainence tools, such as
+	  &man.portupgrade.1;, rely on a database called
+	  <filename>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 this
+	  string.</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>