Second round of @dirrm* cleanup.

Differential Revision:	https://reviews.freebsd.org/D882
Reviewed by:	bcr
Sponsored by:	Absolight

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

@@ -4674,8 +4674,7 @@ PORTVERSION=	1.0</programlisting>
 	<literal>%%PORTDOCS%%</literal> prefix, for example:</para>
 
       <programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
-%%PORTDOCS%%%%DOCSDIR%%/CONTACT
+%%PORTDOCS%%%%DOCSDIR%%/CONTACT</programlisting>
-%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting>
 
       <para>As an alternative to enumerating the documentation files
 	in <filename>pkg-plist</filename>, a port can set the variable

en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml

@@ -93,23 +93,21 @@ OPTIONS_SUB=	yes</programlisting>
       <filename>TMPPLIST</filename>.</para>
 
     <para>Another way of modifying a port's packing list is based on
-      setting the variables <varname>PLIST_FILES</varname>,
+      setting the variables <varname>PLIST_FILES</varname> and
-      <varname>PLIST_DIRS</varname>, and
+      <varname>PLIST_DIRS</varname>.  The value of each variable is
-      <varname>PLIST_DIRSTRY</varname>.  The value of each variable is
       regarded as a list of pathnames to write to
       <filename>TMPPLIST</filename> along with
       <filename>PLIST</filename> contents.  Names listed in
-      <varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
+      <varname>PLIST_FILES</varname> and
-      and <varname>PLIST_DIRSTRY</varname> are subject to
+      <varname>PLIST_DIRS</varname> are subject to
       <literal>%%<replaceable>VAR</replaceable>%%</literal>
       substitution as described above.  Except for that, names from
       <varname>PLIST_FILES</varname> will appear in the final packing
-      list unchanged, while <literal>@dirrm</literal> and
+      list unchanged, while <literal>@dir</literal>
-      <literal>@dirrmtry</literal> will be prepended to names from
+      will be prepended to names from
-      <varname>PLIST_DIRS</varname> and
+      <varname>PLIST_DIRS</varname>.  To take effect,
-      <varname>PLIST_DIRSTRY</varname>, respectively.  To take effect,
+      <varname>PLIST_FILES</varname> and
-      <varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
+      <varname>PLIST_DIRS</varname> must be set before
-      and <varname>PLIST_DIRSTRY</varname> must be set before
       <filename>TMPPLIST</filename> is written, that is, in
       <buildtarget>pre-install</buildtarget> or earlier.</para>
 
@@ -138,33 +136,18 @@ PLIST_SUB+=	X11I386="@comment "
     <sect2 xml:id="plist-dir-cleaning">
       <title>Cleaning Up Empty Directories</title>
 
-      <para>When being de-installed, A port has to remove empty
+      <para>When being de-installed, a port has to remove empty
-	directories it created.  This is usually accomplished by
+	directories it created.  Most of these directories are removed
-	adding <literal>@dirrm</literal> lines for all directories
+	automatically by &man.pkg.8;, but for directories created
-	that are specifically created by the port.  Subdirectories
+	outside of <filename>${PREFIX}</filename>, or empty
-	must be deleted before deleting parent
+	directories, some more work needs to be done.  This is usually
-	directories.</para>
+	accomplished by adding <literal>@dir</literal> lines for those
+	directories.  Subdirectories must be deleted before deleting
+	parent directories.</para>
 
-      <programlisting> :
+      <programlisting>[...]
-lib/X11/oneko/pixmaps/cat.xpm
+@dir /var/games/oneko/saved-games
-lib/X11/oneko/sounds/cat.au
+@dir /var/games/oneko</programlisting>
- :
-@dirrm lib/X11/oneko/pixmaps
-@dirrm lib/X11/oneko/sounds
-@dirrm lib/X11/oneko</programlisting>
-
-      <para>However, sometimes <literal>@dirrm</literal> will give
-	errors because other ports share the same directory.
-	Use <literal>@dirrmtry</literal> to remove only empty
-	directories without warning.</para>
-
-      <programlisting>@dirrmtry share/doc/gimp</programlisting>
-
-      <para>This will neither print any error messages nor cause
-	<command>pkg delete</command> (see &man.pkg-delete.8;) to
-	exit abnormally even if
-	<filename>${PREFIX}/share/doc/gimp</filename> is not empty
-	due to other ports installing some files in there.</para>
     </sect2>
 
     <sect2 xml:id="plist-dir-empty">
@@ -179,10 +162,9 @@ lib/X11/oneko/sounds/cat.au
 	@${MKDIR} ${STAGEDIR}${PREFIX}/some/directory</programlisting>
 
       <para>Add the directory to <filename>pkg-plist</filename>
-	like any other.  For example, if the directory has files
+	like any other.  For example:</para>
-	created when the port is used:</para>
 
-      <programlisting>@dirrmtry some/directory</programlisting>
+      <programlisting>@dir some/directory</programlisting>
     </sect2>
   </sect1>
 
@@ -264,8 +246,8 @@ etc/orbit.conf-dist
       <filename>pkg-plist</filename> (with or without variable
       substitution), or embedded into the
       <filename>Makefile</filename> via
-      <varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
+      <varname>PLIST_FILES</varname> and
-      and <varname>PLIST_DIRSTRY</varname>.  Even if the contents are
+      <varname>PLIST_DIRS</varname>.  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 (for example, using <command>make
@@ -337,7 +319,7 @@ etc/orbit.conf-dist
       <title><literal>@fc</literal>
 	<replaceable>directory</replaceable></title>
 
-      <para>Add a <literal>@dirrmtry</literal> entry for the
+      <para>Add a <literal>@dir</literal> entry for the
 	directory passed as an argument, and run <command>fc-cache
 	  -s</command> on that directory after installation and
 	deinstallation.</para>
@@ -347,7 +329,7 @@ etc/orbit.conf-dist
       <title><literal>@fcfontsdir</literal>
 	<replaceable>directory</replaceable></title>
 
-      <para>Add a <literal>@dirrmtry</literal> entry for the
+      <para>Add a <literal>@dir</literal> entry for the
 	directory passed as an argument, and run <command>fc-cache
 	  -s</command>, <command>mkfontscale</command> and
 	<command>mkfontdir</command> on that directory after
@@ -362,7 +344,7 @@ etc/orbit.conf-dist
       <title><literal>@fontsdir</literal>
 	<replaceable>directory</replaceable></title>
 
-      <para>Add a <literal>@dirrmtry</literal> entry for the
+      <para>Add a <literal>@dir</literal> entry for the
 	directory passed as an argument, and run
 	<command>mkfontscale</command> and
 	<command>mkfontdir</command> on that directory after

en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml

@@ -143,10 +143,7 @@ WWW: http://www.oneko.org/</programlisting>
 	is also called the <quote>packing list</quote> because the
 	package is generated by packing the files listed here.  The
 	pathnames are relative to the installation prefix (usually
-	<filename>/usr/local</filename>.  If the port creates
+	<filename>/usr/local</filename>.</para>
-	directories during installation, make sure to add
-	<literal>@dirrm</literal> lines to remove them when the
-	package is deleted.</para>
 
       <para>Here is a small example:</para>
 
@@ -155,8 +152,7 @@ man/man1/oneko.1.gz
 lib/X11/app-defaults/Oneko
 lib/X11/oneko/cat1.xpm
 lib/X11/oneko/cat2.xpm
-lib/X11/oneko/mouse.xpm
+lib/X11/oneko/mouse.xpm</programlisting>
-@dirrm lib/X11/oneko</programlisting>
 
       <para>Refer to the &man.pkg-create.8; manual page for details
 	on the packing list.</para>
@@ -167,19 +163,17 @@ lib/X11/oneko/mouse.xpm
 	  changes when upgrading the port much easier.</para>
       </note>
 
-      <note>
+      <tip>
 	<para>Creating a packing list manually can be a very tedious
 	  task.  If the port installs a large numbers of files,
 	  <link linkend="plist-autoplist">creating the packing list
 	    automatically</link> might save time.</para>
-      </note>
+      </tip>
 
       <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
+	If the port installs just a handful of files, list them in
-	directories, the files and directories may be listed in the
+	<varname>PLIST_FILES</varname>, within the
-	variables <varname>PLIST_FILES</varname> and
-	<varname>PLIST_DIRS</varname>, 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 these
@@ -190,27 +184,29 @@ lib/X11/oneko/mouse.xpm
 		lib/X11/app-defaults/Oneko \
 		lib/X11/oneko/cat1.xpm \
 		lib/X11/oneko/cat2.xpm \
-		lib/X11/oneko/mouse.xpm
+		lib/X11/oneko/mouse.xpm</programlisting>
-PLIST_DIRS=	lib/X11/oneko</programlisting>
-
-      <para>Of course, <varname>PLIST_DIRS</varname> does not need to
-	be set if a port installs no directories of its own.</para>
 
       <note>
-	<para>Several ports can share a common directory.  In that
+	<para>Usage of <varname>PLIST_FILES</varname> should not be
-	  case, <varname>PLIST_DIRS</varname> must be replaced by
+	  abused.  When looking for the origin of a file, people
-	  <varname>PLIST_DIRSTRY</varname> so that the directory is
+	  usually try to <application>grep</application> through the
-	  removed only if empty, otherwise it is silently ignored.
+	  <filename>pkg-plist</filename> files in the ports tree.
-	  <varname>PLIST_DIRS</varname> and
+	  Listing files in <varname>PLIST_FILES</varname> in the
-	  <varname>PLIST_DIRSTRY</varname> are equivalent to using
+	  <filename>Makefile</filename> makes that search more
-	  <literal>@dirrm</literal> and <literal>@dirrmtry</literal>
+	  difficult.</para>
-	  in <filename>pkg-plist</filename>, as described in
-	  <xref linkend="plist-dir-cleaning"/>.</para>
       </note>
 
+      <tip>
+	<para>If a port needs to create an empty directory, or creates
+	  directories outside of <filename>${PREFIX}</filename> during
+	  installation, refer to <xref linkend="plist-dir-cleaning"/>
+	  for more information.</para>
+      </tip>
+
       <para>The price for this way of listing a port's files and
-	directories is that then command sequences described in
+	directories is that the keywords described in
-	&man.pkg-create.8; cannot be used.  Therefore, it is suitable
+	&man.pkg-create.8; and <xref linkend="plist-keywords"/> cannot
+	be used.  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