Index: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
@@ -318,6 +318,19 @@
   <sect1 xml:id="plist-keywords">
     <title>Expanding Package List with Keywords</title>
 
+    <para>All keywords can also take optional arguments in
+      parentheses.  The arguments are owner, group, and mode.  This
+      argument is used on the file or directory referenced.
+      To change the owner, group, and mode of a configuration file,
+      use:</para>
+
+    <programlisting>@sample(games,games,640) etc/config.sample</programlisting>
+
+    <para>The arguments are optional.  If only the group and mode
+      need to be changed, use:</para>
+
+    <programlisting>@sample(,games,660) etc/config.sample</programlisting>
+
     <!-- Try and keep the keywords alphanumerically sorted -->
 
     <sect2 xml:id="plist-keywords-fc">
@@ -401,10 +414,22 @@
     <sect2 xml:id="plist-keywords-base">
       <title>Base Keywords</title>
 
-      <para>There are a few historic keywords that are hardcoded, and
+      <para>There are a few keywords that are hardcoded, and
 	documented in &man.pkg-create.8;.  For the sake of
 	completeness, they are also documented here.</para>
 
+      <sect3 xml:id="plist-keywords-base-empty">
+	<title><literal>@</literal>
+	  [<replaceable>file</replaceable>]</title>
+
+	<para>The empty keyword is a placeholder to use when the
+	  file's owner, group, or mode need to be changed.  For
+	  example, to set the group of the file to
+	  <literal>games</literal> and add the setgid bit, add:</para>
+
+	<programlisting>@(,games,2755) sbin/daemon</programlisting>
+      </sect3>
+
       <sect3 xml:id="plist-keywords-base-cwd">
 	<title><literal>@cwd</literal>
 	  [<replaceable>directory</replaceable>]</title>
@@ -497,6 +522,13 @@
 	  same as that used by &man.chmod.1;.  Use without an arg to
 	  set back to default permissions (mode of the file while
 	  being packed).</para>
+
+	<important>
+	  <para>This must be a numeric mode, like
+	    <literal>644</literal>, <literal>4755</literal>, or
+	    <literal>600</literal>.  It cannnot be a relative mode
+	    like <literal>u+s</literal>.</para>
+	</important>
       </sect3>
 
       <sect3 xml:id="plist-keywords-base-owner">
@@ -526,22 +558,37 @@
 	<para>This line is ignored when packing.</para>
       </sect3>
 
+      <sect3 xml:id="plist-keywords-base-dir">
+	<title><literal>@dir</literal>
+	  <replaceable>directory</replaceable></title>
+
+	<para>Declare directory name.  By default, directories created
+	  under <varname>PREFIX</varname> by a package installation
+	  are automatically removed.  Use this when an empty directory
+	  under <varname>PREFIX</varname> needs to be created, or when
+	  the directory needs to have non default owner, group, or
+	  mode.  Directories outside of <varname>PREFIX</varname> need
+	  to be registered.  For example,
+	  <filename>/var/db/${PORTNAME}</filename> needs to have a
+	  <literal>@dir</literal> entry whereas
+	  <filename>${PREFIX}/share/${PORTNAME}</filename> does not if
+	  it contains files or uses the default owner, group, and
+	  mode.</para>
+      </sect3>
+
       <sect3 xml:id="plist-keywords-base-dirrm">
 	<title><literal>@dirrm</literal>
-	  <replaceable>directory</replaceable></title>
+	  <replaceable>directory</replaceable> (Deprecated)</title>
 
 	<para>Declare directory name to be deleted at deinstall time.
-	  By default, directories created by a package installation
-	  are not deleted when the package is deinstalled.  This
-	  provides an explicit directory cleanup method.  These
-	  directives must appear at the end of the package list.  If
-	  the directory is not empty a warning is printed, and the
-	  directory is not removed.</para>
+	  By default, directories created under
+	  <varname>PREFIX</varname> by a package installation are
+	  deleted when the package is deinstalled.</para>
       </sect3>
 
       <sect3 xml:id="plist-keywords-base-dirrmtry">
 	<title><literal>@dirrmtry</literal>
-	  <replaceable>directory</replaceable></title>
+	  <replaceable>directory</replaceable> (Deprecated)</title>
 
 	<para>Declare directory name to be removed, as for
 	  <literal>@dirrm</literal>, but does not issue a warning if
@@ -555,9 +602,9 @@
       <para>Package list files can be extended by keywords that are
 	defined in the <filename
 	  class="directory">${PORTSDIR}/Keywords</filename> directory.
-	The settings for each keyword lives in a
-	<acronym>YAML</acronym> file named
-	<filename><replaceable>keyword</replaceable>.yaml</filename>.
+	The settings for each keyword are stored in a
+	<acronym>UCL</acronym> file named
+	<filename><replaceable>keyword</replaceable>.ucl</filename>.
 	The file must contain at least one of the next
 	sections:</para>
 
@@ -595,11 +642,20 @@
 	      </varlistentry>
 
 	      <varlistentry>
+		<term><literal>dir</literal></term>
+
+		<listitem>
+		  <para>Register a directory to be created on
+		    install and removed on deinstall.</para>
+		</listitem>
+	      </varlistentry>
+
+	      <varlistentry>
 		<term><literal>dirrm</literal></term>
 
 		<listitem>
 		  <para>Register a directory to be deleted on
-		    deinstall.</para>
+		    deinstall.  Deprecated.</para>
 		</listitem>
 	      </varlistentry>
 
@@ -608,7 +664,7 @@
 
 		<listitem>
 		  <para>Register a directory to try and deleted on
-		    deinstall.</para>
+		    deinstall.  Deprecated.</para>
 		</listitem>
 	      </varlistentry>
 
@@ -701,13 +757,14 @@
 	  removed when deinstalling the package.</para>
 
 	<programlisting>actions: [dirrmtry]
-post-deinstall: |
-  echo "Directory %D/%@ removed."</programlisting>
+post-deinstall: &lt;&lt;EOD
+  echo "Directory %D/%@ removed."
+EOD</programlisting>
       </example>
 
       <example xml:id="plist-keywords-sample-example">
 	<title>Real Life Example, How the <literal>@sample</literal>
-	  Could be Implemented</title>
+	  is Implemented</title>
 
 	<para>This keyword does three things, it adds the
 	  <replaceable>filename</replaceable> passed as an argument to
@@ -719,7 +776,7 @@
 	  configuration file if it has not been modified.</para>
 
 	<programlisting>actions: [file]
-post-install: |
+post-install: &lt;&lt;EOD
   case "%@" in
   /*) sample_file="%@" ;;
   *) sample_file="%D/%@" ;;
@@ -728,7 +785,8 @@
   if ! [ -f "${target_file}" ]; then
     /bin/cp -p "${sample_file}" "${target_file}"
   fi
-pre-deinstall: |
+EOD
+pre-deinstall: &lt;&lt;EOD
   case "%@" in
   /*) sample_file="%@" ;;
   *) sample_file="%D/%@" ;;
@@ -736,7 +794,10 @@
   target_file="${sample_file%.sample}"
   if cmp -s "${target_file}" "${sample_file}"; then
     rm -f "${target_file}"
-  fi</programlisting>
+  else
+    echo "You may need to manually remove ${target_file} if it's no longer needed."
+  fi
+EOD</programlisting>
       </example>
     </sect2>
   </sect1>