PLIST_FILES in the Porter's Handbook

[Yar Tikhiy]

PLIST_FILES and PLIST_DIRS are not documented yet.
Could anybody review my attempt to fill up the gap?
Thanks.

-- 
Yar

Index: book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.432
diff -u -r1.432 book.sgml
--- book.sgml	19 Jun 2004 22:37:46 -0000	1.432
+++ book.sgml	19 Jun 2004 23:36:00 -0000
@@ -230,6 +230,39 @@
 		linkend="porting-autoplist">creating the packing list
 		automatically</link> might save time.</para>
 	  </note>
+
+	  <para>There is only one case when <filename>pkg-plist</filename>
+	    can be omitted from a port.  If the port installs just a handful
+	    of files, and perhaps directories, the files and directories may
+	    be listed in the variables <makevar>PLIST_FILES</makevar> and
+	    <makevar>PLIST_DIRS</makevar>, respectively, within the port's
+	    <filename>Makefile</filename>.  For instance, we could get along
+	    without <filename>pkg-plist</filename> in the above
+	    <filename>oneko</filename> port by adding the
+	    following lines to the <filename>Makefile</filename>:</para>
+
+	  <programlisting>PLIST_FILES=	bin/oneko \
+		lib/X11/app-defaults/Oneko \
+		lib/X11/oneko/cat1.xpm \
+		lib/X11/oneko/cat2.xpm \
+		lib/X11/oneko/mouse.xpm
+PLIST_DIRS=	lib/X11/oneko</programlisting>
+
+	  <para>Of course, <makevar>PLIST_DIRS</makevar> should be left
+	    unset if a port installs no directories of its own.</para>
+
+	  <para>The price for this way of listing port's files and
+	    directories is that you cannot use command sequences
+	    described in &man.pkg.create.1;.  Therefore, it is suitable
+	    only for simple ports and makes them even simpler.  At the
+	    same time, it has the advantage of reducing the number of files
+	    in the ports collection.  Please consider using this technique
+	    before you resort to <filename>pkg-plist</filename>.</para>
+
+	  <para>Later we will see how <filename>pkg-plist</filename>
+	    and <makevar>PLIST_FILES</makevar> can be used to fulfil
+	    <link linkend="porting-plist">more sophisticated
+	    tasks</link>.</para>
 	</sect2>
       </sect1>
 
@@ -4935,6 +4968,24 @@
 	  needs to edit the resulting file, do so in
 	  <maketarget>post-install</maketarget> to a file named
 	  <filename><makevar>TMPPLIST</makevar></filename>.</para>
+
+	<para>Another possibility to modify port's packing list is based
+	  on setting the variables <makevar>PLIST_FILES</makevar> and
+	  <makevar>PLIST_DIRS</makevar>.  The value of each variable
+	  is regarded as a list of pathnames to
+	  write to <filename><makevar>TMPPLIST</makevar></filename>
+	  along with <filename><makevar>PLIST</makevar></filename>
+	  contents.  Names listed in <makevar>PLIST_FILES</makevar>
+	  and <makevar>PLIST_DIRS</makevar> are subject to
+	  <literal>%%VAR%%</literal> substitution, as described above.
+	  Except for that, names from <makevar>PLIST_FILES</makevar>
+	  will appear in the final packing list unchanged,
+	  while <literal>@dirrm</literal> will be
+	  prepended to names from <makevar>PLIST_DIRS</makevar>.
+	  To take effect, <makevar>PLIST_FILES</makevar> and
+	  <makevar>PLIST_DIRS</makevar> must be set before
+	  <filename><makevar>TMPPLIST</makevar></filename> is written,
+	  i.e. in <maketarget>pre-install</maketarget> or earlier.</para>
       </sect1>
 
       <sect1 id="pkg-names">