Index: en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
@@ -5523,4 +5523,41 @@
       </listitem>
     </itemizedlist>
   </sect1>
+
+  <sect1 xml:id="shell-completion">
+    <title>Shell Completion Files</title>
+
+    <para>Many modern shells (including bash, tcsh, and zsh) support
+      parameter and/or option tab-completion.  This support usually
+      comes from completion files, which contain the definitions for
+      how tab completion will work for a certain command.  Ports
+      sometimes ship with their own completion files, or porters may
+      have created them themselves.</para>
+
+    <para>When available, completion files should always be
+      installed.  It is not necessary to make an
+      <varname>OPTION</varname> for it, but if you do, always add it
+      to <varname>OPTIONS_DEFAULT</varname>.</para>
+
+    <table frame="none" xml:id="shell-completion-paths">
+      <title>Shell completion file paths</title>
+
+      <tgroup cols="2">
+	<tbody>
+	  <row>
+	    <entry><command>bash</command></entry>
+	    <entry><filename>${PREFIX}/etc/bash_completion.d/</filename></entry>
+	  </row>
+
+	  <row>
+	    <entry><command>zsh</command></entry>
+	    <entry><filename>${PREFIX}/share/zsh/site-functions/</filename></entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+
+    <para>Do not register any dependencies on the shells themselves.
+    </para>
+  </sect1>
 </chapter>