Add various wordsmithing and clarifying text to the book.

The vast majority of this work is

Submitted by:	linimon
PR:		docs/53422, docs/53425

1 files changed, 332 insertions, 105 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index 3f840adda4..97e2f0540d 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -44,11 +44,25 @@
     &bookinfo.legalnotice;
   </bookinfo>
 
+    <chapter id="why-port">
+      <title>Introduction</title>
+
+      <para>The FreeBSD ports collection is the way almost everyone
+	installs applications ("ports") on FreeBSD.  Like everything
+ 	else about FreeBSD, it is primarily a volunteer effort.
+ 	It is important to keep this in mind when reading this
+ 	document.</para>
+ 
+      <para>In FreeBSD, anyone may submit a new port, or volunteer
+ 	to maintain an existing port if it is unmaintained&mdash;you
+ 	do not need any special commit privileges to do so.</para>
+
+    </chapter>
 
     <chapter id="own-port">
       <title>Making a port yourself</title>
 
-      <para>So, now you are interested in making your own port or
+      <para>So, you are still interested in making your own port or
 	upgrading an existing one?  Great!</para>
 
       <para>What follows are some guidelines for creating a new port for
@@ -66,8 +80,9 @@
 	<para>Only a fraction of the variables
 	  (<makevar><replaceable>VAR</replaceable></makevar>) that can be
 	  overridden are mentioned in this document.  Most (if not all)
-	  are documented at the start of <filename>bsd.port.mk</filename>.
-	  This file uses a non-standard tab setting.
+	  are documented at the start of <filename>bsd.port.mk</filename>;
+	  the others probably ought to be.
+	  Note that this file uses a non-standard tab setting:
 	  <application>Emacs</application> and
 	  <application>Vim</application> should recognize the setting on
 	  loading the file.  Both &man.vi.1; and
@@ -81,7 +96,8 @@
       <title>Quick Porting</title>
 
       <para>This section tells you how to do a quick port.  In many cases, it
-	is not enough, but we will see.</para>
+	is not sufficient, so you will have to read further on into
+	the document.</para>
 
       <para>First, get the original tarball and put it into
 	<makevar>DISTDIR</makevar>, which defaults to
@@ -499,8 +515,8 @@ lib/X11/oneko/mouse.xpm
 	    make sure all  the stages up to that one are completed and call
 	    the real targets or scripts, and they are not intended to be
 	    changed.  If you want to fix the extraction, fix
-	    <maketarget>do-extract</maketarget>, but never ever touch
-	    <maketarget>extract</maketarget>!</para>
+	    <maketarget>do-extract</maketarget>, but never ever change
+	    the way <maketarget>extract</maketarget> operates!</para>
 	</note>
 
 	<para>Now that you understand what goes on when the user types
@@ -518,16 +534,26 @@ lib/X11/oneko/mouse.xpm
 	  <emphasis>mainstream</emphasis> sources when and where you
 	  can.</para>
 
+	<para>You will need to set the variable <makevar>MASTER_SITES</makevar>
+	  to reflect where the original tarball resides.  You will find
+	  convenient shorthand definitions for most mainstream sites
+	  in <filename>bsd.sites.mk</filename>.  Please use these
+	  sites&mdash;and the associated definitions&mdash;if
+	  at all possible, to help avoid the problem of having the same
+	  information repeated over again many times in the source base.
+	  As these sites tend to change over time, this becomes a
+	  maintenance nightmare for everyone involved.</para>
+
 	<para>If you cannot find a FTP/HTTP site that is well-connected to the
 	  net, or can only find sites that have irritatingly non-standard
 	  formats, you might want to put a copy on a reliable FTP or HTTP
-	  server that you control (e.g., your home page).  Make sure you set
-	  <makevar>MASTER_SITES</makevar> to reflect your choice.</para>
+	  server that you control (e.g., your home page).</para>
 
 	<para>If you cannot find somewhere convenient and reliable to put the
 	  distfile
 	  we can <quote>house</quote> it ourselves
-	  on <hostid>ftp.FreeBSD.org</hostid>.
+	  on <hostid>ftp.FreeBSD.org</hostid>; however, this is the
+	  least-preferred solution.
 	  The distfile must be placed into
 	  <filename>~/public_distfiles/</filename> of someone's
 	  <hostid>freefall</hostid> account.
@@ -537,9 +563,13 @@ lib/X11/oneko/mouse.xpm
 	  <makevar>MASTER_SITE_SUBDIR</makevar> to their
 	  <hostid>freefall</hostid> username.</para>
 
-	<para>If your port's distfile changes all the time for no good reason,
-	  consider putting the distfile in your home page and listing it as
-	  the first <makevar>MASTER_SITES</makevar>.  This will prevent users
+	<para>If your port's distfile changes all the time without any
+	  kind of version update by the author,
+	  consider putting the distfile on your home page and listing it as
+	  the first <makevar>MASTER_SITES</makevar>.  If you can, try
+	  to talk the port author out of doing this; it
+	  really does help to establish some kind of source code control.
+	  Hosting your own version will prevent users
 	  from getting <errorname>checksum mismatch</errorname> errors, and
 	  also reduce the workload of maintainers of our FTP site.  Also, if
 	  there is only one master site for the port, it is recommended that
@@ -646,12 +676,13 @@ lib/X11/oneko/mouse.xpm
 	<title>Handling user input</title>
 
 	<para>If your port requires user input to build, configure, or install,
-	  then set <makevar>IS_INTERACTIVE</makevar> in your <filename>Makefile</filename>.  This
+	  you must set <makevar>IS_INTERACTIVE</makevar> in your <filename>Makefile</filename>.  This
 	  will allow <quote>overnight builds</quote> to skip your port if the
 	  user sets the variable <envar>BATCH</envar> in his environment (and
 	  if the user sets the variable <envar>INTERACTIVE</envar>, then
 	  <emphasis>only</emphasis> those ports requiring interaction are
-	  built).</para>
+	  built).  This will save a lot of wasted time on the set of
+	  machines that continually build ports (see below).</para>
 
 	<para>It is also recommended that if there are reasonable default
 	  answers to the questions, you check the
@@ -807,10 +838,12 @@ lib/X11/oneko/mouse.xpm
 	  </itemizedlist>
 
 	  <para>A rule of thumb is to ask yourself whether a change
-	    committed to a port is something which someone, somewhere,
+	    committed to a port is something which everyone
 	    would benefit from having (either because of an
 	    enhancement, fix, or by virtue that the new package will
-	    actually work for them). If yes, the
+	    actually work at all), and weigh that against that fact
+	    that it will cause everyone who regularly updates their
+	    ports tree to be compelled to update. If yes, the
 	    <makevar>PORTREVISION</makevar> should be bumped so that
 	    automated tools (e.g.  &man.pkg.version.1;)
 	    will highlight the fact that a new package is
@@ -832,7 +865,7 @@ lib/X11/oneko/mouse.xpm
 	    <makevar>PORTEPOCH</makevar> version should be increased.
 	    If <makevar>PORTEPOCH</makevar> is nonzero it is appended
 	    to the package name as described in section 0 above.
-	    <makevar>PORTEPOCH</makevar> is never decreased or reset
+	    <makevar>PORTEPOCH</makevar> must never be decreased or reset
 	    to zero, because that would cause comparison to a package
 	    from an earlier epoch to fail (i.e. the package would not
 	    be detected as out of date): the new version number (e.g.
@@ -842,6 +875,12 @@ lib/X11/oneko/mouse.xpm
 	    automated tools and found to be greater than the implied
 	    suffix <literal>,0</literal> on the earlier package.</para>
 
+	  <para>Dropping or resetting <makevar>PORTEPOCH</makevar>
+	    incorrectly leads
+	    to no end of grief; if you do not understand the above discussion,
+	    please keep after it until you do, or ask questions on
+	    the mailing lists.</para>
+
 	  <para>It is expected that <makevar>PORTEPOCH</makevar> will
 	    not be used for the majority of ports, and that sensible
 	    use of <makevar>PORTVERSION</makevar> can often pre-empt
@@ -893,7 +932,7 @@ PORTREVISION=	1</programlisting>
 	    <literal>0.1.0</literal>, not <quote>what comes after
 	      0.9</quote> - oops, too late now). Since the new minor
 	    version <literal>2</literal> is numerically less than the
-	    previous version <literal>10</literal> the
+	    previous version <literal>10</literal>, the
 	    <makevar>PORTEPOCH</makevar> must be bumped to manually
 	    force the new package to be detected as <quote>newer</quote>. Since it
 	    is a new vendor release of the code,
@@ -924,7 +963,8 @@ PORTEPOCH=	1</programlisting>
 	      installed the <literal>gtkmumble-0.10_1</literal> package would not detect
 	      the <literal>gtkmumble-0.3</literal> package as newer, since
 	      <literal>3</literal> is still numerically less than
-	      <literal>10</literal>.</para>
+	      <literal>10</literal>.  Remember, this is the whole point of
+	      <makevar>PORTEPOCH</makevar> in the first place.</para>
 	  </note>
 	</sect3>
       </sect2>
@@ -940,11 +980,11 @@ PORTEPOCH=	1</programlisting>
 	  <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
 	  Make sure this conforms to our <link
 	  linkend="porting-pkgname">guidelines for a good package
-	  name</link>.  In particular, you are not allowed to use a
+	  name</link>.  In particular, you are <emphasis>not</emphasis> allowed to use a
 	  hyphen (<literal>-</literal>) in
 	  <makevar>PORTVERSION</makevar>.  Also, if the package name
 	  has the <replaceable>language-</replaceable> or the
-	  <replaceable>-compiled.specifics</replaceable> part, use
+	  <replaceable>-compiled.specifics</replaceable> part (see below), use
 	  <makevar>PKGNAMEPREFIX</makevar> and
 	  <makevar>PKGNAMESUFFIX</makevar>, respectively.  Do not make
 	  them part of <makevar>PORTNAME</makevar>.</para>
@@ -955,7 +995,7 @@ PORTEPOCH=	1</programlisting>
 
       <para>The following are the conventions you should follow in naming your
 	packages.  This is to have our package directory easy to scan, as
-	there are already lots and lots of packages and users are going to
+	there are already thousands of packages and users are going to
 	turn away if they hurt their eyes!</para>
 
       <para>The package name should look like
@@ -1219,16 +1259,29 @@ PORTEPOCH=	1</programlisting>
 	<para>If your port truly belongs to something that is different from
 	  all the existing ones, you can even create a new category name.  In
 	  that case, please send mail to the &a.ports; to propose a new
-	  category.</para>
+	  category.  However, in general, until there are more than a
+	  handful of ports which could be reclassified into the category
+	  you propose, you will probably be turned down.</para>
+
+	<note><para>Occasionally someone proposes reorganizing the categories
+	  with either a 2-level structure, or some other kind of keyword
+	  structure.  To date, nothing has come of any of these proposals
+	  because, while they are very easy to make, the effort involved to
+	  retrofit the entire existing ports collection with any kind of
+	  reorganization is daunting to say the very least.  Please read
+	  the history of these proposals in the mailing list archives before
+	  you post this idea; furthermore, you should be prepared to be
+	  challenged to offer a working prototype.</para></note>
       </sect2>
 
       <sect2 id="porting-categories">
 	<title>Current list of categories</title>
 
-	<para>First, this is the current list of port categories.  Those
+	<para>Here is the current list of port categories.  Those
 	  marked with an asterisk (<literal>*</literal>) are
 	  <emphasis>virtual</emphasis> categories&mdash;those that do not have
-	  a corresponding subdirectory in the ports tree.</para>
+	  a corresponding subdirectory in the ports tree.  They are only
+	  used as secondary categories, and only for search purposes.</para>
 
 	<note>
 	  <para>For non-virtual categories, you will find a one-line
@@ -1238,11 +1291,12 @@ PORTEPOCH=	1</programlisting>
 	</note>
 
 	<informaltable frame="none">
-	  <tgroup cols="2">
+	  <tgroup cols="3">
 	    <thead>
 	      <row>
 		<entry>Category</entry>
 		<entry>Description</entry>
+		<entry>Notes</entry>
 	      </row>
 	    </thead>
 
@@ -1250,104 +1304,122 @@ PORTEPOCH=	1</programlisting>
 	      <row>
 		<entry><filename>accessibility*</filename></entry>
 		<entry>Ports to help disabled users.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>afterstep*</filename></entry>
-		<entry>Ports to support the AfterStep window manager.</entry>
+		<entry>Ports to support the
+		  <ulink url="http://www.afterstep.org">AfterStep</ulink>
+		  window manager.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>arabic</filename></entry>
 		<entry>Arabic language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>archivers</filename></entry>
 		<entry>Archiving tools.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>astro</filename></entry>
 		<entry>Astronomical ports.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>audio</filename></entry>
 		<entry>Sound support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>benchmarks</filename></entry>
 		<entry>Benchmarking utilities.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>biology</filename></entry>
 		<entry>Biology-related software.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>cad</filename></entry>
 		<entry>Computer aided design tools.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>chinese</filename></entry>
 		<entry>Chinese language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>comms</filename></entry>
-		<entry>Communication software.  Mostly software to talk to
-		  your serial port.</entry>
+		<entry>Communication software.</entry>
+		<entry>Mostly software to talk to your serial port.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>converters</filename></entry>
 		<entry>Character code converters.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>databases</filename></entry>
 		<entry>Databases.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>deskutils</filename></entry>
 		<entry>Things that used to be on the desktop before
 		  computers were invented.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>devel</filename></entry>
-		<entry>Development utilities.  Do not put libraries here just
-		  because they are libraries&mdash;unless they truly do not
-		  belong anywhere else, they should not be in this
-		  category.</entry>
+		<entry>Development utilities.</entry>
+		<entry>Do not put libraries here just because they are
+		  libraries&mdash;unless they truly do not belong anywhere
+		  else, they should not be in this category.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>dns</filename></entry>
 		<entry>DNS-related software.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>editors</filename></entry>
-		<entry>General editors.  Specialized editors go in the section
-		  for those tools (e.g., a mathematical-formula editor will go
+		<entry>General editors.</entry>
+		<entry>Specialized editors go in the section for those
+		  tools (e.g., a mathematical-formula editor will go
 		  in <filename>math</filename>).</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>elisp*</filename></entry>
 		<entry>Emacs-lisp ports.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>emulators</filename></entry>
-		<entry>Emulators for other operating systems.  Terminal
-		  emulators do <emphasis>not</emphasis> belong
+		<entry>Emulators for other operating systems.</entry>
+		<entry>Terminal emulators do <emphasis>not</emphasis> belong
 		  here&mdash;X-based ones should go to
 		  <filename>x11</filename> and text-based ones to either
 		  <filename>comms</filename> or <filename>misc</filename>,
@@ -1357,17 +1429,19 @@ PORTEPOCH=	1</programlisting>
 	      <row>
 		<entry><filename>finance</filename></entry>
 		<entry>Monetary, financial and related applications.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>french</filename></entry>
 		<entry>French language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>ftp</filename></entry>
-		<entry>FTP client and server utilities.  If your
-		  port speaks both FTP and HTTP, put it in
+		<entry>FTP client and server utilities.</entry
+		<entry>If your port speaks both FTP and HTTP, put it in
 		  <filename>ftp</filename> with a secondary
 		  category of <filename>www</filename>.</entry>
 	      </row>
@@ -1375,191 +1449,231 @@ PORTEPOCH=	1</programlisting>
 	      <row>
 		<entry><filename>games</filename></entry>
 		<entry>Games.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>german</filename></entry>
 		<entry>German language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>gnome*</filename></entry>
-		<entry>Ports from the GNU Object Model Environment (GNOME)
+		<entry>Ports from the <ulink
+		  url="http://www.gnome.org">GNOME</ulink>
 		  Project.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>graphics</filename></entry>
 		<entry>Graphics utilities.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>haskell*</filename></entry>
 		<entry>Software related to the Haskell language.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>hebrew</filename></entry>
 		<entry>Hebrew language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>hungarian</filename></entry>
 		<entry>Hungarian language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>ipv6*</filename></entry>
 		<entry>IPv6 related software.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>irc</filename></entry>
 		<entry>Internet Relay Chat utilities.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>japanese</filename></entry>
 		<entry>Japanese language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>java</filename></entry>
 		<entry>Software related to the Java language.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>kde*</filename></entry>
-		<entry>Ports from the K Desktop Environment (KDE)
+		<entry>Ports from the <ulink url="http://www.kde.org">K Desktop Environment (KDE)</ulink>
 		  Project.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>korean</filename></entry>
 		<entry>Korean language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>lang</filename></entry>
 		<entry>Programming languages.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>linux*</filename></entry>
 		<entry>Linux applications and support utilities.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>lisp*</filename></entry>
 		<entry>Software related to the Lisp language.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>mail</filename></entry>
 		<entry>Mail software.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>math</filename></entry>
 		<entry>Numerical computation software and other utilities
 		  for mathematics.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>mbone</filename></entry>
 		<entry>MBone applications.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>misc</filename></entry>
-		<entry>Miscellaneous utilities&mdash;basically things that
+		<entry>Miscellaneous utilities</entry>
+		<entry>Basically things that
 		  do not belong anywhere else.  This is the only category
 		  that should not appear with any other non-virtual category.
 		  If you have <literal>misc</literal> with something else in
 		  your <makevar>CATEGORIES</makevar> line, that means you can
 		  safely delete <literal>misc</literal> and just put the port
-		  in that other subdirectory!</entry>
+		  in that other subdirectory!  If at all possible, try to
+		  find a better category for your port than
+		  <literal>misc</literal> ports tend to get overlooked
+		  in here.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>multimedia</filename></entry>
 		<entry>Multimedia software.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>net</filename></entry>
 		<entry>Miscellaneous networking software.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>news</filename></entry>
 		<entry>USENET news software.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>offix*</filename></entry>
-		<entry>Ports from the OffiX suite.</entry>
+		<entry>Ports from the <ulink url="http://leb.net/OffiX/">OffiX</ulink> suite.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>palm</filename></entry>
-		<entry>Software support for the Palm(tm) series.</entry>
+		<entry>Software support for the <ulink url="http://www.palm.com/">Palm&trade;</ulink> series.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>parallel*</filename></entry>
 		<entry>Applications dealing with parallelism in computing.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>pear*</filename></entry>
 		<entry>Ports related to the Pear PHP framework.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>perl5*</filename></entry>
-		<entry>Ports that require <literal>perl</literal> version 5 to run.</entry>
+		<entry>Ports that require <application>Perl</application> version 5 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>picobsd</filename></entry>
-		<entry>Ports to support PicoBSD.</entry>
+		<entry>Ports to support <ulink url="http://people.FreeBSD.org/~picobsd/">PicoBSD</ulink>.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>plan9*</filename></entry>
-		<entry>Various programs from Plan9.</entry>
+		<entry>Various programs from <ulink url="http://www.cs.bell-labs.com/plan9dist/">Plan9</ulink>.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>polish</filename></entry>
 		<entry>Polish language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>portuguese</filename></entry>
 		<entry>Portuguese language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>print</filename></entry>
-		<entry>Printing software.  Desktop publishing tools
+		<entry>Printing software.</entry>
+		<entry>Desktop publishing tools
 		  (previewers, etc.) belong here too.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>python*</filename></entry>
-		<entry>Software related to the Python language.</entry>
+		<entry>Software related to the <ulink url="http://www.python.org/">Python</ulink> language.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>ruby*</filename></entry>
-		<entry>Software related to the Ruby language.</entry>
+		<entry>Software related to the <ulink url="http://www.ruby-lang.org/">Ruby</ulink> language.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>russian</filename></entry>
 		<entry>Russian language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
@@ -1568,111 +1682,134 @@ PORTEPOCH=	1</programlisting>
 		  categories such as <filename>astro</filename>,
 		  <filename>biology</filename> and
 		  <filename>math</filename>.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>security</filename></entry>
 		<entry>Security utilities.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>shells</filename></entry>
 		<entry>Command line shells.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>sysutils</filename></entry>
 		<entry>System utilities.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tcl76*</filename></entry>
 		<entry>Ports that use Tcl version 7.6 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tcl80*</filename></entry>
 		<entry>Ports that use Tcl version 8.0 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tcl81*</filename></entry>
 		<entry>Ports that use Tcl version 8.1 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tcl82*</filename></entry>
 		<entry>Ports that use Tcl version 8.2 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tcl83*</filename></entry>
 		<entry>Ports that use Tcl version 8.3 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>textproc</filename></entry>
-		<entry>Text processing utilities.  It does not include
+		<entry>Text processing utilities.</entry>
+		<entry>It does not include
 		  desktop publishing tools, which go to <filename>print</filename>.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tk42*</filename></entry>
 		<entry>Ports that use Tk version 4.2 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tk80*</filename></entry>
 		<entry>Ports that use Tk version 8.0 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tk81*</filename></entry>
 		<entry>Ports that use Tk version 8.1 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tk82*</filename></entry>
 		<entry>Ports that use Tk version 8.2 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tk83*</filename></entry>
 		<entry>Ports that use Tk version 8.3 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>tkstep80*</filename></entry>
 		<entry>Ports that use TkSTEP version 8.0 to run.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>ukrainian</filename></entry>
 		<entry>Ukrainian language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>vietnamese</filename></entry>
 		<entry>Vietnamese language support.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>windowmaker*</filename></entry>
 		<entry>Ports to support the WindowMaker window
 		  manager.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>www</filename></entry>
-		<entry>Software related to the World Wide Web.  HTML language
+		<entry>Software related to the World Wide Web.</entry>
+		<entry>HTML language
 		  support belongs here too.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>x11</filename></entry>
-		<entry>The X Window System and friends.  This category is only
+		<entry>The X Window System and friends.</entry>
+		<entry>This category is only
 		  for software that directly supports the window system.  Do not
-		  put regular X applications here.  If your port is an X
+		  put regular X applications here; most of them should go
+		  into other <filename>x11-*</filename> categories (see below).
+		  If your port <emphasis>is</emphasis> an X
 		  application, define <makevar>USE_XLIB</makevar> (implied by
 		  <makevar>USE_IMAKE</makevar>) and put it in the appropriate
 		  categories.  Also, many of them go into other
@@ -1682,36 +1819,43 @@ PORTEPOCH=	1</programlisting>
 	      <row>
 		<entry><filename>x11-clocks</filename></entry>
 		<entry>X11 clocks.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>x11-fm</filename></entry>
 		<entry>X11 file managers.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>x11-fonts</filename></entry>
 		<entry>X11 fonts and font utilities.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>x11-servers</filename></entry>
 		<entry>X11 servers.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>x11-toolkits</filename></entry>
 		<entry>X11 toolkits.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>x11-wm</filename></entry>
 		<entry>X11 window managers.</entry>
+		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>zope*</filename></entry>
-		<entry>Zope support.</entry>
+		<entry><ulink url="http://www.zope.org/">Zope</ulink> support.</entry>
+		<entry></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
@@ -1737,11 +1881,12 @@ PORTEPOCH=	1</programlisting>
 	  <listitem>
 	    <para>Specific categories win over less-specific ones.  For
 	      instance, an HTML editor should be listed as <filename>www
-		editors</filename>, not the other way around.  Also, you do not
-	      need to list <filename>net</filename> when the port belongs to
+		editors</filename>, not the other way around.  Also, you should not
+	      list <filename>net</filename> when the port belongs to
 	      any of <filename>irc</filename>, <filename>mail</filename>,
 	      <filename>mbone</filename>, <filename>news</filename>,
-	      <filename>security</filename>, or <filename>www</filename>.</para>
+	      <filename>security</filename>, or <filename>www</filename>, as
+	      <filename>net</filename> is included implicitly.</para>
 	  </listitem>
 
 	  <listitem>
@@ -1771,8 +1916,10 @@ PORTEPOCH=	1</programlisting>
 	<para>If you are not sure about the category, please put a comment to
 	  that effect in your &man.send-pr.1; submission so we can
 	  discuss it before we import it.  If you are a committer, send a note
-	  to the &a.ports; so we can discuss it first&mdash;too often new ports are
-	  imported to the wrong category only to be moved right away.</para>
+	  to the &a.ports; so we can discuss it first.  Too often, new ports are
+	  imported to the wrong category only to be moved right away.
+	  This causes unnecessary and undesirable bloat in the master
+	  source repository.</para>
       </sect2>
     </sect1>
 
@@ -1828,9 +1975,10 @@ PORTEPOCH=	1</programlisting>
 
 	<para>It is recommended that you put multiple sites on this list,
 	  preferably from different continents.  This will safeguard against
-	  wide-area network problems, and we are even planning to add support
+	  wide-area network problems.  We are even planning to add support
 	  for automatically determining the closest master site and fetching
-	  from there!</para>
+	  from there; having multiple sites will go a long way towards
+	  helping this effort.</para>
 
 	<para>If the original tarball is part of one of the popular
 	  archives such as X-contrib, GNU, or Perl CPAN, you may be able
@@ -1876,8 +2024,10 @@ EXTRACT_SUFX=  .tgz</programlisting>
 	  neither of these are set then <makevar>EXTRACT_SUFX</makevar>
 	  defaults to <literal>.tar.gz</literal>.</para>
 
-	<para>You never need to set both <makevar>EXTRACT_SUFX</makevar> and
-	  <makevar>DISTFILES</makevar>.</para>
+        <note>
+	  <para>You never need to set both <makevar>EXTRACT_SUFX</makevar> and
+	    <makevar>DISTFILES</makevar>.</para>
+        </note>
       </sect2>
 
       <sect2>
@@ -1965,6 +2115,10 @@ EXTRACT_ONLY=  source.tar.gz</programlisting>
 	  sites and subdirectories
 	  (<literal>MASTER_SITES:n</literal>)</title>
 
+	<para>(Consider this to be a somewhat <quote>advanced topic</quote>;
+	  those new to this document may wish to skip this section at first).
+	  </para>
+
 	<para>This section has information on the fetching mechanism
 	  known as both <literal>MASTER_SITES:n</literal> and
 	  <literal>MASTER_SITES_NN</literal>.  We will refer to this
@@ -2096,7 +2250,7 @@ DISTFILES=      source1.tar.gz:source1 \
 		<replaceable>n</replaceable> is
 		<literal>[^:,]+</literal>, i.e.,
 		<replaceable>n</replaceable> could conceptually be any
-		alphanumerical string but we will limit it to
+		alphanumeric string but we will limit it to
 		<literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for
 		now.</para>
 
@@ -2637,6 +2791,12 @@ PATCHFILES=     patch1:test</programlisting>
 	<para>Set your mail-address here.  Please.  <!-- smiley
 	  --><emphasis>:-)</emphasis></para>
 
+	<para>The format used should be <literal>user@hostname.domain</literal>.
+	  Please do not include any descriptive text such as your real
+	  name in this entry&mdash;that merely confuses
+	  <filename>bsd.port.mk</filename>.  Instead, put that information
+	  into your <filename>pkg-descr</filename>.</para>
+
 	<para>For a detailed description of the responsibilities of maintainers,
 	  refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
 	    Makefiles</ulink> section.</para>
@@ -2667,7 +2827,7 @@ PATCHFILES=     patch1:test</programlisting>
 	<para>This is a one-line description of the port.
 	  <emphasis>Please</emphasis> do not include the package name (or
 	  version number of the software) in the comment.  The comment
-	  should begin with a capital, and end without a period.  Here
+	  should begin with a capital and end without a period.  Here
 	  is an example:</para>
 
 	<programlisting>COMMENT=       A cat chasing a mouse all over the screen</programlisting>
@@ -2957,7 +3117,9 @@ PATCHFILES=     patch1:test</programlisting>
 	  <para>When you type <command>make clean</command>, its dependencies
 	    are automatically cleaned too.  If you do not wish this to happen,
 	    define the variable <makevar>NOCLEANDEPENDS</makevar> in your
-	    environment.</para>
+	    environment.  This may be particularly desirable if the port
+	    has something that takes a long time to rebuild in its
+	    dependency list, such as KDE, GNOME or Mozilla.</para>
 
 	  <para>To depend on another port unconditionally, use the
 	    variable <makevar>${NONEXISTENT}</makevar> as the first field
@@ -3016,13 +3178,33 @@ PATCHFILES=     patch1:test</programlisting>
 	<makevar>WANT_IMLIB</makevar>, and
 	<makevar>WANT_GNOME</makevar>.</para>
       </sect2>
+
+      <sect2>
+        <title>Circular dependencies are fatal</title>
+
+        <important>
+          <para>Do not introduce any circular dependencies into the
+          ports tree!</para>
+        </important>
+
+        <para>The ports building technology does not tolerate
+          circular dependencies.  If you introduce one, you will have
+          someone, somewhere in the world, whose FreeBSD installation will
+          break almost immediately, with many others quickly to follow.
+          These can really be hard to detect; if in doubt, before
+          you make that change, make sure you have done the following:
+          <command>cd /usr/ports; make index</command>.  That process
+          can be quite slow on older machines, but you may be able to
+          save a large number of people&mdash;including yourself&mdash;
+          a lot of grief in the process.</para>
+      </sect2>
     </sect1>
 
     <sect1 id="makefile-wrkdir">
       <title>Specifying the working directory</title>
 
       <para>Each port is extracted in to a working directory, which must be
-	writable.  The ports system assumes that the
+	writable.  The ports system defaults to having the
 	<makevar>DISTFILES</makevar> unpack in to a directory called
 	<literal>${DISTNAME}</literal>.  In other words, if you have
 	set:</para>
@@ -3034,7 +3216,7 @@ PORTVERSION=   1.0</programlisting>
 	<filename>foo-1.0</filename>, and the rest of the files are located
 	under that directory.</para>
 
-      <para>There are a number of variables you can set if that is not the
+      <para>There are a number of variables you can override if that is not the
 	case.</para>
 
       <sect2>
@@ -3157,7 +3339,7 @@ PORTVERSION=   1.0</programlisting>
 	  <literal>@unexec /sbin/ldconfig -R</literal> pair into your
 	  <filename>pkg-plist</filename> file, so that a user who installed
 	  the package can start using the shared library immediately and
-	  deinstallation will not cause the system to still believe the
+	  de-installation will not cause the system to still believe the
 	  library is there.</para>
 
 	<para>If you need, you can override the default location where the new
@@ -3224,8 +3406,10 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 
 	<para>This variable indicates that although we are allowed to generate
 	  binary packages, we are not allowed to put those packages, or the
-	  port's <makevar>DISTFILES</makevar>, on to CDROM for resale.  The
-	  <makevar>DISTFILES</makevar> will still be available via FTP.</para>
+	  port's <makevar>DISTFILES</makevar>, onto a CDROM (or DVD-ROM)
+	  for resale.  The
+	  <makevar>DISTFILES</makevar> will still be available via FTP
+	  (or HTTP if you set it up that way.)</para>
 
 	<para><makevar>NO_PACKAGE</makevar> and <makevar>NO_CDROM</makevar>
 	  can be set simultaneously.</para>
@@ -3236,11 +3420,15 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 
 	<para>Set this variable if the application's license also forbids us
 	  from mirroring the application's <makevar>DISTFILES</makevar> via
-	  FTP.</para>
+	  FTP (or HTTP if you set it up that way.)</para>
 
 	<para>Also set this if the application's license has general
 	  restrictions on who may use it, e.g. the application is for
 	  non-commercial use only.</para>
+
+	<para>Note that the port committer should add an entry to
+	  <filename>/usr/ports/LEGAL</filename> describing exactly
+	  what the restriction entails.</para>
       </sect2>
 
       <sect2>
@@ -3636,31 +3824,31 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
     <sect1 id="using-bison">
       <title>Using Bison</title>
 
-      <para></para>
+      <para>This section is yet to be written.</para>
     </sect1>
 
     <sect1 id="using-java">
       <title>Using Java</title>
 
-      <para></para>
+      <para>This section is yet to be written.</para>
     </sect1>
 
     <sect1 id="using-python">
       <title>Using Python</title>
 
-      <para></para>
+      <para>This section is yet to be written.</para>
     </sect1>
 
     <sect1 id="using-emacs">
       <title>Using Emacs</title>
 
-      <para></para>
+      <para>This section is yet to be written.</para>
     </sect1>
 
     <sect1 id="using-ruby">
       <title>Using Ruby</title>
 
-      <para></para>
+      <para>This section is yet to be written.</para>
     </sect1>
     </chapter>
 
@@ -4029,7 +4217,7 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 
 	<para>This variable will be set by <filename>bsd.port.mk</filename> to
 	  be the appropriate reference to the Motif library.  Please patch the
-	  source to use this wherever the Motif library is referenced in the
+	  source of your port to reference this wherever the Motif library is referenced in the
 	  <filename>Makefile</filename> or
 	  <filename>Imakefile</filename>.</para>
 
@@ -4064,7 +4252,7 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 
       <para>If your port installs fonts for the X Window System, put them in
 	<filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>.
-	This directory is new to <application>XFree86 3.3.3</application>.  If it does not exist,
+	This directory was new to <application>XFree86 3.3.3</application>.  If it does not exist,
 	please create it, and print out a message urging the user to update
 	their <application>XFree86</application> to 3.3.3 or newer, or at least add this directory to the
 	font path in <filename>/etc/XF86Config</filename>.</para>
@@ -4075,8 +4263,8 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 
       <para>If your package needs to install GNU info files, they should be
 	listed in the <makevar>INFO</makevar> variable (without the trailing
-	<literal>.info</literal>), and appropriate installation/deinstallation
-	code will be automaticaly added to the temporary
+	<literal>.info</literal>), and appropriate installation/de-installation
+	code will be automatically added to the temporary
 	<filename>pkg-plist</filename> before package registration.</para>
     </chapter>
 
@@ -4112,7 +4300,7 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 	  is installed with &man.pkg.add.1; you can do this via the
 	  <filename>pkg-install</filename> script.  This script will
 	  automatically be added to the package, and will be run twice by
-	  &man.pkg.add.1;.  The first time as
+	  &man.pkg.add.1;: the first time as
 	  <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
 	  PRE-INSTALL</literal> and the second time as
 	  <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME} POST-INSTALL</literal>.
@@ -4149,13 +4337,13 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 	<para>If your port needs to determine if it should install or not, you
 	  can create a <filename>pkg-req</filename> <quote>requirements</quote>
 	  script.  It will be invoked automatically at
-	  installation/deinstallation time to determine whether or not
-	  installation/deinstallation should proceed.</para>
+	  installation/de-installation time to determine whether or not
+	  installation/de-installation should proceed.</para>
 
 	<para>The script will be run at installation time by
 	  &man.pkg.add.1; as
 	  <literal>pkg-req &dollar;{PKGNAME} INSTALL</literal>.
-	  At deinstallation time it will be run by
+	  At de-installation time it will be run by
 	  &man.pkg.delete.1; as
 	  <literal>pkg-req &dollar;{PKGNAME} DEINSTALL</literal>.</para>
       </sect1>
@@ -4174,10 +4362,10 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 	  <literal>%%PERL_VERSION%%</literal> will be substituted for
 	  appropriately.  The value of <literal>%%OSREL%%</literal> is the
 	  numeric revision of the operating system (e.g.,
-	  <literal>2.2.7</literal>).  <literal>%%PERL_VERSION%%</literal> is
-	  the full version number of <literal>perl</literal> (e.g.,
+	  <literal>4.9</literal>).  <literal>%%PERL_VERSION%%</literal> is
+	  the full version number of <command>perl</command> (e.g.,
 	  <literal>5.00502</literal>) and <literal>%%PERL_VER%%</literal>
-	  is the <literal>perl</literal> version number minus
+	  is the <command>perl</command> version number minus
 	  the patchlevel (e.g., <literal>5.005</literal>).</para>
 
 	<para>If you need to make other substitutions, you can set the
@@ -4305,7 +4493,7 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 	  set, in which case it will be <makevar>X11BASE</makevar> (default
 	  <filename>/usr/X11R6</filename>).</para>
 
-	<para>Not hard-coding <filename>/usr/local</filename> or
+	<para>Avoiding the hard-coding of <filename>/usr/local</filename> or
 	  <filename>/usr/X11R6</filename> anywhere in the source will make the
 	  port much more flexible and able to cater to the needs of other
 	  sites.  For X ports that use <command>imake</command>, this is
@@ -4362,7 +4550,7 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
       <sect1 id="testing-freshports">
 	<title>FreshPorts sanity tests</title>
 
-	<para><ulink url="http://www.FreshPorts.org/">FreshPorts</ulink> has
+	<para><ulink url="http://www.FreshPorts.org/"></ulink> has
 	  a sanity test feature which automatically tests each commit to the
 	  FreeBSD ports tree.  If subscribed to this service, you will be
 	  notified of any errors which FreshPorts detects during sanity
@@ -4414,6 +4602,12 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 	please compress and uuencode it; otherwise, just include it in the PR
 	as is.</para>
 
+      <para>Finally, please see the
+        <ulink url="../../articles/problem-reports/pr-writing.html">
+        Writing the problem report</ulink> section in the Problem
+        Reports article for more information about how to write
+        useful problem reports.</para>
+
       <important>
 	<para>If your upgrade is motivated by security concerns or a
 	  serious fault in the currently committed port, please notify
@@ -4433,14 +4627,18 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
     <chapter id="porting-dads">
       <title>Dos and Don'ts</title>
 
+      <sect1 id="dads-intro">
+	<title>Introduction</title>
+
       <para>Here is a list of common dos and don'ts that you encounter during
 	the porting process.  You should check your own port against this list,
-	but you can also check ports in the PR database that others have
+	but you can also check ports in the <ulink url="http://www.freebsd.org/cgi/query-pr-summary.cgi?query">PR database</ulink> that others have
 	submitted.  Submit any comments on ports you check as described in
 	<ulink url="../../articles/contributing/contrib-how.html#CONTRIB-GENERAL">Bug Reports and General
 	  Commentary</ulink>.  Checking ports in the PR database will both make
 	it faster for us to commit them, and prove that you know what you are
 	doing.</para>
+      </sect1>
 
       <sect1 id="dads-strip">
 	<title>Stripping Binaries</title>
@@ -4508,7 +4706,7 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 	  <makevar>WRKDIR</makevar>.  <makevar>WRKDIR</makevar> is the only
 	  place that is guaranteed to be writable during the port build (see
 	  <ulink url="../handbook/ports-using.html#PORTS-CD">
-	  compiling ports from CDROM</ulink> for an
+	  installing ports from a CDROM</ulink> for an
 	  example of building ports from a read-only tree).  If you need to
 	  modify one of the <filename>pkg-<replaceable>*</replaceable></filename>
 	  files, do so by <link
@@ -4538,7 +4736,7 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 	  compilation based upon what version of Unix it is running under.  If
 	  you need to make such changes to the code for conditional
 	  compilation, make sure you make the changes as general as possible
-	  so that we can back-port code to FreeBSD 1.x systems and cross-port
+	  so that we can back-port code to older FreeBSD systems and cross-port
 	  to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD,
 	  NetBSD, and OpenBSD.</para>
 
@@ -4607,13 +4805,13 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 	  <listitem>
 	    <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is defined to
 	      be <literal>2</literal>.  In earlier versions, it is
-	      <literal>1</literal>.  Later versions will bump it to match
+	      <literal>1</literal>.  Later versions always bump it to match
 	      their major version number.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you need to tell the difference between a FreeBSD 1.x
-	      system and a FreeBSD 2.x or 3.x system, usually the right answer
+	      system and a FreeBSD 2.x or above system, usually the right answer
 	      is to use the <literal>BSD</literal> macros described above.  If
 	      there actually is a FreeBSD specific change (such as special
 	      shared library options when using <command>ld</command>) then it
@@ -5719,7 +5917,7 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 
 	      <row>
 		<entry><makevar>OSVERSION</makevar></entry>
-		<entry>The numeric version of the operating system, same as
+		<entry>The numeric version of the operating system; the same as
 		  <link
 		    linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry>
 	      </row>
@@ -5727,7 +5925,9 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 	      <row>
 		<entry><makevar>PORTOBJFORMAT</makevar></entry>
 		<entry>The object format of the system
-		  (<literal>aout</literal> or <literal>elf</literal>)</entry>
+		  (<literal>elf</literal> or <literal>aout</literal>;
+		  note that for <quote>modern</quote> versions of FreeBSD,
+		  <literal>aout</literal> is deprecated.)</entry>
 	      </row>
 
 	      <row>
@@ -5779,6 +5979,11 @@ post-install:
 .if ${PORTOBJFORMAT} == "aout"
        ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
 .endif</programlisting>
+
+        <para>You did remember to use tab instead of spaces after
+          <literal>BROKEN=</literal> and
+          <literal>TCL_LIB_FILE=</literal>, did you not?
+          <!-- smiley -->:-).</para>
       </sect1>
 
       <sect1 id="dads-documentation">
@@ -5855,7 +6060,7 @@ post-install:
 	  the subdirectory with the port's name, which is incorrect.  Also,
 	  many ports put everything except binaries, header files and manual
 	  pages in the a subdirectory of <filename>lib</filename>, which does
-	  not bode well with the BSD paradigm.  Many of the files should be
+	  not work well with the BSD paradigm.  Many of the files should be
 	  moved to one of the following: <filename>etc</filename>
 	  (setup/configuration files), <filename>libexec</filename>
 	  (executables started internally), <filename>sbin</filename>
@@ -5874,7 +6079,7 @@ post-install:
 	<title>Cleaning up empty directories</title>
 
 	<para>Do make your ports clean up after themselves when they are
-	  deinstalled.  This is usually accomplished by adding
+	  de-installed.  This is usually accomplished by adding
 	  <literal>@dirrm</literal> lines for all directories that are
 	  specifically created by the port.  You need to delete subdirectories
 	  before you can delete parent directories.</para>
@@ -5918,7 +6123,8 @@ lib/X11/oneko/sounds/cat.au
 	  999.</para>
 
 	<!-- Please keep this list sorted by uid -->
-	<programlisting>majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
+	<programlisting>bind:*:53:53:Bind Sandbox:/:/sbin/nologin
+majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
 cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
 gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
 proxy:*:62:62:Packet Filter pseudo-user:/nonexistent:/nonexistent
@@ -5973,6 +6179,14 @@ bacula:*:910:910:Bacula Daemon:/var/db/bacula:/sbin/nologin</programlisting>
 	  <makevar>EXTRACT*</makevar> instead, and using
 	  <makevar>GNU_CONFIGURE</makevar> instead of <literal>CONFIGURE_ARGS
 	    += --prefix=&dollar;{PREFIX}</literal>.</para>
+
+	<para>If you find yourself having to write a lot
+	  of new code to try to do something, please go back and review
+	  <filename>bsd.port.mk</filename> to see if it contains an
+	  existing implementation of what you are trying to do.  While
+	  hard to read, there are a great many seemingly-hard problems for
+	  which <filename>bsd.port.mk</filename> already provides a
+	  shorthand solution.</para>
       </sect1>
 
       <sect1 id="dads-cc">
@@ -5980,7 +6194,13 @@ bacula:*:910:910:Bacula Daemon:/var/db/bacula:/sbin/nologin</programlisting>
 	  <makevar>CXX</makevar></title>
 
 	<para>The port should respect both <makevar>CC</makevar>
-	  and <makevar>CXX</makevar> variables.  If it does not,
+	  and <makevar>CXX</makevar> variables.  What we mean by this
+	  is that the port should not set the values of these variables
+	  absolutely, overriding existing values; instead, it should append
+	  whatever values it needs to the existing values.  This is so that
+	  build options that affect all ports can be set globally.</para>
+
+	<para>If the port does not respect these variables,
 	  please add <literal>NO_PACKAGE=ignores either cc or
 	  cxx</literal> to the <filename>Makefile</filename>.</para>
 
@@ -6011,7 +6231,13 @@ bacula:*:910:910:Bacula Daemon:/var/db/bacula:/sbin/nologin</programlisting>
 	<title>Respect <makevar>CFLAGS</makevar></title>
 
 	<para>The port should respect the <makevar>CFLAGS</makevar> variable.
-	  If it does not, please add <literal>NO_PACKAGE=ignores
+	  What we mean by this is that the port should not set the value of
+	  this variable absolutely, overriding the existing value; instead,
+	  it should append whatever values it needs to the existing value.
+	  This is so that build options that affect all ports can be set
+	  globally.</para>
+
+	<para>If it does not, please add <literal>NO_PACKAGE=ignores
 	    cflags</literal> to the <filename>Makefile</filename>.</para>
 
 	<para>An example of a <filename>Makefile</filename> respecting
@@ -6332,7 +6558,8 @@ pre-install:
 
       <para>Other resources to assist port maintainers include a list of
 	<ulink url="http://bento.FreeBSD.org/">package building logs and
-	errors </ulink> and the <ulink
+	errors</ulink> hosted on the <literal>bento cluster</literal>,
+	and also the <ulink
 	  url="http://people.FreeBSD.org/~fenner/portsurvey/">FreeBSD
 	  Ports distfiles survey</ulink>.</para>
     </chapter>