From c59b4557502741d013eea367f4f562bd19d8b53e Mon Sep 17 00:00:00 2001
From: Eitan Adler <eadler@FreeBSD.org>
Date: Fri, 7 Dec 2012 13:00:49 +0000
Subject: [PATCH] Update and expand on the pkg-descr explanation in the
 porter's handbook.

Submitted by:	danfe
Approved by:	bcr (mentor)
---
 .../books/porters-handbook/book.xml           | 31 ++++++++++++++++---
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/book.xml b/en_US.ISO8859-1/books/porters-handbook/book.xml
index b034e78746..02b425dccc 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.xml
@@ -181,11 +181,32 @@ USE_IMAKE=	yes
 	    <filename>README</filename> or manpage</emphasis>; too
 	    often they are not a concise description of the port or
 	    are in an awkward format (e.g., manpages have justified
-	    spacing).  If the ported software has an official WWW
-	    homepage, you should list it here.  Prefix
-	    <emphasis>one</emphasis> of the websites with
-	    <literal>WWW:</literal> so that automated tools will work
-	    correctly.</para>
+	    spacing, as it looks particularly bad with monospaced
+	    fonts).</para>
+	</note>
+
+	<para>Well-written description text should describe the port
+	  completely enough that users would not have to consult its
+	  documentation or visit its website to understand what does it
+	  do, how it can be useful for them, what particularly nice
+	  features (if any) does it have, etc.  You might want to
+	  mention certain requirements (e.g. the graphical toolkit),
+	  heavy dependencies, runtime environment, or implementation
+	  languages, to help users to decide if they want to install
+	  this port or not.</para>
+
+	<para>If the ported software has an official WWW homepage, it
+	  should be listed here.  Prepend <emphasis>one</emphasis> of
+	  the websites (pick the most common one) with
+	  <literal>WWW:</literal> (followed by single space) so that
+	  automated tools will work correctly.  If the URI is the root
+	  of the website or directory, it should be terminated with a
+	  slash.</para>
+
+	<note>
+	  <para>If the listed webpage for a port is not available, try
+	    to search the Internet first to see if the official site
+	    moved, was renamed, or is hosted elsewhere.</para>
 	</note>
 
 	<para>The following example shows how your