PORTDOCS in the Porter's Handbook

[Yar Tikhiy]

Hi folks,

The neat PORTDOCS variable deserves more attention in
the Porter's Handbook, doesn't it?

Hope I got it right...  Could anybody review the below
patch?  Thank you!

-- 
Yar

Index: book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.429
diff -u -r1.429 book.sgml
--- book.sgml	16 Jun 2004 09:48:26 -0000	1.429
+++ book.sgml	19 Jun 2004 12:05:22 -0000
@@ -4218,9 +4218,8 @@
 	  JDK, it is therefore a complex task to specify the packing list
 	  (<filename>pkg-plist</filename>).  This is one reason why
 	  porters are strongly encouraged to use the
-	  <makevar>PORTDOCS</makevar> macro.  This feature is yet well
-	  documented, so you should refer to <filename>bsd.port.mk</filename>
-	  itself for further information.  Moreover, even if you can
+	  <makevar>PORTDOCS</makevar> macro.
+	  Moreover, even if you can
 	  predict the set of files that will be generated by
 	  <command>javadoc</command>, the size of the resulting
 	  <filename>pkg-plist</filename> advocates for the use of
@@ -6784,6 +6783,26 @@
 	  <para><filename>pkg-message</filename> does not need to be added to
 	    <filename>pkg-plist</filename>.</para>
 	</note>
+
+	<para>Recently a new feature was introduced to the ports framework
+	 in order to facilitate registering port documentation.  Instead of
+	 listing all the documentation files in the packing list with the
+	 somewhat clumsy <literal>%%PORTDOCS%%</literal> prefix, now a porter
+	 can set the variable <makevar>PORTDOCS</makevar> to a list of
+	 file names and shell glob patterns relative to
+	 <makevar>DOCSDIR</makevar>.  If a directory is listed or matched
+	 by a glob pattern, the entire subtree of contained files and
+	 directories will be registered.  <makevar>PORTDOCS</makevar>
+	 should not be set if <makevar>NOPORTDOCS</makevar> is in
+	 effect.  Installing the documentation at <makevar>PORTDOCS</makevar>
+	 as shown above remains up to the port itself.
+	 A typical example of utilizing <makevar>PORTDOCS</makevar>
+	 looks as follows:</para>
+
+        <programlisting>.if !defined(NOPORTDOCS)
+	PORTDOCS=	*
+.endif</programlisting>
+
       </sect1>
 
       <sect1 id="dads-subdirs">