svn commit: r42608 - head/en_US.ISO8859-1/books/porters-handbook

[Warren Block]

Author: wblock
Date: Mon Sep  2 18:21:26 2013
New Revision: 42608
URL: http://svnweb.freebsd.org/changeset/doc/42608

Log:
  Mention PLIST_DIRSTRY.  Committed version is slightly edited from the
  second diff in the PR.
  
  PR:		 docs/181080
  Submitted by:	 Frederic Culot <culot at FreeBSD.org>

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/book.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.xml	Sun Sep  1 22:36:52 2013	(r42607)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.xml	Mon Sep  2 18:21:26 2013	(r42608)
@@ -278,6 +278,19 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
 	<para>Of course, <makevar>PLIST_DIRS</makevar> should be left
 	  unset if a port installs no directories of its own.</para>
 
+	<note>
+
+	  <para>Several ports can share a common directory.  In that
+	    case, <makevar>PLIST_DIRS</makevar> should be replaced by
+	    <makevar>PLIST_DIRSTRY</makevar> so that the directory is
+	    removed only if empty, otherwise it is silently ignored.
+	    <makevar>PLIST_DIRS</makevar> and
+	    <makevar>PLIST_DIRSTRY</makevar> are equivalent to using
+	    <literal>@dirrm</literal> and <literal>@dirrmtry</literal>
+	    in <filename>pkg-plist</filename>, as described in
+	    <xref linkend="plist-dir-cleaning"/>.</para>
+	</note>
+
 	<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
@@ -9917,21 +9930,26 @@ PLIST_SUB+=	X11="@comment "
 	<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
+      <para>Another way of modifying a port's packing list is based
+	on setting the variables <makevar>PLIST_FILES</makevar>,
+	<makevar>PLIST_DIRS</makevar>, and
+	<makevar>PLIST_DIRSTRY</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
+	listed in <makevar>PLIST_FILES</makevar>,
+	<makevar>PLIST_DIRS</makevar>, and
+	<makevar>PLIST_DIRSTRY</makevar> are subject to
 	<literal>%%<replaceable>VAR</replaceable>%%</literal>
-	substitution, as described above.  Except for that, names from
+	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
+	packing list unchanged, while <literal>@dirrm</literal> and
+	<literal>@dirrmtry</literal> will
+	be prepended to names from <makevar>PLIST_DIRS</makevar>
+	and <makevar>PLIST_DIRSTRY</makevar>, respectively.  To
+	take effect, <makevar>PLIST_FILES</makevar>,
+	<makevar>PLIST_DIRS</makevar>, and
+	<makevar>PLIST_DIRSTRY</makevar> must be set before
 	<filename><makevar>TMPPLIST</makevar></filename> is written,
 	i.e., in <maketarget>pre-install</maketarget> or
 	earlier.</para>
@@ -10059,8 +10077,9 @@ etc/orbit.conf.sample
 	<filename>pkg-plist</filename> file (with or without variable
 	substitution), or embedded into the
 	<filename>Makefile</filename> via
-	<makevar>PLIST_FILES</makevar> and
-	<makevar>PLIST_DIRS</makevar>.  Even if the contents are
+	<makevar>PLIST_FILES</makevar>,
+	<makevar>PLIST_DIRS</makevar>, and
+	<makevar>PLIST_DIRSTRY</makevar>.  Even if the contents are
 	auto-generated by a tool or a target in the Makefile
 	<emphasis>before</emphasis> the inclusion into the Ports
 	Collection by a committer, this is still considered a static