diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index 09fe45d3c5..72adc91f13 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -4254,9 +4254,7 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 	  JDK, it is therefore a complex task to specify the packing list
 	  (<filename>pkg-plist</filename>).  This is one reason why
 	  porters are strongly encouraged to use the
-	  <makevar>PORTDOCS</makevar> macro.  This feature is yet well
-	  documented, so you should refer to <filename>bsd.port.mk</filename>
-	  itself for further information.  Moreover, even if you can
+	  <makevar>PORTDOCS</makevar> macro.  Moreover, even if you can
 	  predict the set of files that will be generated by
 	  <command>javadoc</command>, the size of the resulting
 	  <filename>pkg-plist</filename> advocates for the use of
@@ -6820,7 +6818,8 @@ post-install:
 	${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR}
 .endif</programlisting>
 
-	<para>Here are some variables and how they are expanded when used
+	<para>Here are some variables and how they are expanded
+	  by default when used
 	  in the <filename>Makefile</filename>:</para>
 
 	<itemizedlist>
@@ -6858,6 +6857,28 @@ post-install:
 	  <para><filename>pkg-message</filename> does not need to be added to
 	    <filename>pkg-plist</filename>.</para>
 	</note>
+
+	<para>As an alternative to enumerating the documentation files
+	  in <filename>pkg-plist</filename>, a port can set the variable
+	  <makevar>PORTDOCS</makevar> to a list of file names and shell
+	  glob patterns to add to the final packing list.
+	  The names will be relative to <makevar>DOCSDIR</makevar>.
+	  Therefore, a port that utilizes <makevar>PORTDOCS</makevar> and
+	  uses a non-default location for its documentation should set
+	  <makevar>DOCSDIR</makevar> accordingly.
+	  If a directory is listed in <makevar>PORTDOCS</makevar>
+	  or matched by a glob pattern from this variable,
+	  the entire subtree of contained files and directories will be
+	  registered in the final packing list.  <makevar>PORTDOCS</makevar>
+	  should not be set if <makevar>NOPORTDOCS</makevar> is in
+	  effect.  Installing the documentation at <makevar>PORTDOCS</makevar>
+	  as shown above remains up to the port itself.
+	  A typical example of utilizing <makevar>PORTDOCS</makevar>
+	  looks as follows:</para>
+
+        <programlisting>.if !defined(NOPORTDOCS)
+	PORTDOCS=	*
+.endif</programlisting>
       </sect1>
 
       <sect1 id="dads-subdirs">