- Add documentation for USES (and its potential values). Note that now it

comes with a separate file that could be easily expanded by ports people.

Requested by:	bapt

en_US.ISO8859-1/books/porters-handbook/Makefile

@@ -20,6 +20,7 @@ INSTALL_ONLY_COMPRESSED?=
 
 # XML content
 SRCS=  book.xml
+SRCS+= uses.xml
 
 # Use the local DSSSL file
 DSLHTML?= 	${.CURDIR}/freebsd.dsl

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

@@ -3,7 +3,6 @@
 	"../../../share/xml/freebsd42.dtd" [
 <!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
 %entities;
-]>
 
 <!--
      The FreeBSD Documentation Project
@@ -11,6 +10,9 @@
      $FreeBSD$
 -->
 
+<!ENTITY values.uses SYSTEM "uses.xml">
+]>
+
 <book lang='en'>
   <bookinfo>
     <title>FreeBSD Porter's Handbook</title>
@@ -3793,6 +3795,20 @@ ALWAYS_KEEP_DISTFILES=	yes
 	  is the same as <makevar>DEPENDS_TARGET</makevar>.</para>
       </sect2>
 
+      <sect2 id="uses">
+	<title><makevar>USES</makevar></title>
+
+	<para>There several parameters exist for defining different kind
+	  of features and dependencies that the port in question uses.
+	  They can be specified by adding the following line to the
+	  <filename>Makefile</filename> of the port:</para>
+
+	<programlisting>USES= feature[:arguments]</programlisting>
+
+	<para>For the complete list of such values, please see <xref
+	    linkend="uses-values"/>.</para>
+      </sect2>
+
       <sect2 id="use-vars">
 	<title><makevar>USE_<replaceable>*</replaceable></makevar></title>
 
@@ -16861,4 +16877,29 @@ pre-install:
 	about creating has already been submitted.</para>
     </sect1>
   </chapter>
+
+  <chapter id="appendices">
+    <title>Appendices</title>
+
+    <sect1 id="uses-values">
+      <title>Values of <makevar>USES</makevar></title>
+
+      <table frame="none">
+	<title>Values of <makevar>USES</makevar></title>
+
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Feature</entry>
+	      <entry>Arguments</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    &values.uses;
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect1>
+  </chapter>
 </book>

en_US.ISO8859-1/books/porters-handbook/uses.xml

@@ -0,0 +1,26 @@
+<!--
+
+  The FreeBSD Documentation Project
+
+  $FreeBSD$
+
+  This file documents the values of the USES make variable.  The format is
+  easy to grasp from the already-added entries below (or use this scheme
+  below as a skeleton):
+
+<row>
+  <entry><literal>FEATURE</literal></entry>
+  <entry>ARGUMENTS</entry>
+  <entry>DESCRIPTION</entry>
+</row>
+
+-->
+
+<row>
+  <entry><literal>pathfix</literal></entry>
+  <entry>none</entry>
+  <entry>Look for the <filename>Makefile.in</filename> and
+    <filename>configure</filename> files in the port's associated
+    sources and fix common paths to make sure they respect the &os;
+    hierarchy.</entry>
+</row>