svn commit: r40293 - head/en_US.ISO8859-1/books/porters-handbook

[Eitan Adler]

Author: eadler
Date: Fri Dec  7 13:00:49 2012
New Revision: 40293
URL: http://svnweb.freebsd.org/changeset/doc/40293

Log:
  Update and expand on the pkg-descr explanation in the porter's handbook.
  
  Submitted by:	danfe
  Approved by:	bcr (mentor)

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/book.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.xml	Fri Dec  7 13:00:46 2012	(r40292)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.xml	Fri Dec  7 13:00:49 2012	(r40293)
@@ -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