[ports committer:] in a few cases, the Handbook introduces a concept,

elaborates on the concept, and then justifies the reason for the concept.
This make the document read a little bit strangely.  This fix switches
the latter two.  Very little new text is introduced, just some rewording.

PR:			docs/61653 (partial)
Reviewed by:		ceri
Approved by:		ceri

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -348,8 +348,19 @@ lib/X11/oneko/mouse.xpm
 	  Also add a short description of the program you ported
 	  to the <quote>Description</quote> field of the PR and
 	  the shar or uuencoded tarfile to the
-	  <quote>Fix</quote> field.  The latter one helps the committers
+	  <quote>Fix</quote> field.</para>
-	  a lot, who use scripts for the ports-work.</para>
+
+	<note>
+	  <para>You can make our work a lot easier, if you use a good
+	    description in the synopsis of the problem report.
+	    We prefer something like
+	    <quote>New port: &lt;category&gt;/&lt;portname&gt;
+	    &lt;short description of the port&gt;</quote> for new ports and
+	    <quote>Update port: &lt;category&gt;/&lt;portname&gt;
+	    &lt;short description of the update&gt;</quote> for port updates.
+	    If you stick to this scheme, the chance that someone will take a
+	    look at your PR soon is much better.</para>
+	</note>
 
 	<para>One more time, <emphasis>do not include the original source
 	    distfile, the <filename>work</filename> directory, or the package
@@ -375,18 +386,6 @@ lib/X11/oneko/mouse.xpm
 	  <ulink url="../../articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</ulink>
 	  and other files. Isn't that great?!? <!-- smiley
 	  -->:-)</para>
-
-	<note>
-	  <para>You can make our work a lot easier, if you use a good
-	    description in the synopsis of the problem report.
-	    We prefer something like
-	    <quote>New port: &lt;short description of the port&gt;</quote> for
-	    new ports and
-	    <quote>Update port: &lt;category&gt;/&lt;port&gt; &lt;short description
-	    of the update&gt;</quote> for port updates.
-	    If you stick to this scheme, the chance that one takes a look at
-	    your PR soon is much bigger.</para>
-	</note>
       </sect1>
     </chapter>
 
@@ -757,8 +756,13 @@ lib/X11/oneko/mouse.xpm
 	    every increase of <makevar>PORTVERSION</makevar> (i.e.
 	    every time a new official vendor release is made), and
 	    appended to the package name if non-zero.
-	    <makevar>PORTREVISION</makevar> is increased each time a
+	    Changes to <makevar>PORTREVISION</makevar> are
-	    change is made to the FreeBSD port which significantly
+	    used by automated tools (e.g.  &man.pkg.version.1;)
+	    to highlight the fact that a new package is
+	    available.</para>
+
+	  <para><makevar>PORTREVISION</makevar> should be increased
+	    each time a change is made to the port which significantly
 	    affects the content or structure of the derived
 	    package.</para>
 
@@ -846,10 +850,7 @@ lib/X11/oneko/mouse.xpm
 	    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
+	    <makevar>PORTREVISION</makevar> should be bumped.</para>
-	    automated tools (e.g.  &man.pkg.version.1;)
-	    will highlight the fact that a new package is
-	    available.</para>
 	</sect3>
 
 	<sect3>
@@ -1814,8 +1815,7 @@ PORTEPOCH=	1</programlisting>
 		  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
+		  category.</entry>
-		  <filename>x11-*</filename> categories (see below).</entry>
 	      </row>
 
 	      <row>
@@ -2793,7 +2793,9 @@ 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>.
+	<para>Note that only a single address without the comment part is
+	  allowed as a <makevar>MAINTAINER</makevar> value.
+	  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
@@ -2803,9 +2805,6 @@ PATCHFILES=     patch1:test</programlisting>
 	  refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
 	    Makefiles</ulink> section.</para>
 
-	<para>Note that only a single address without comment part is
-	  allowed as a <makevar>MAINTAINER</makevar> value.</para>
-
 	<para>If the maintainer of a port does not respond to an update
 	  request from a user after two weeks (excluding major public
 	  holidays), then that is considered a maintainer timeout, and the
@@ -4634,23 +4633,23 @@ PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 
       <para>If the maintainer asks you to do the upgrade or the maintainer
 	is <literal>ports@FreeBSD.org</literal>,
-	please make the upgrade and send the
+	please make the upgrade and save the result of the
 	recursive <command>diff</command> output
 	of the new and old
-	ports directories to us (e.g., if your modified port directory is
+	ports directories (e.g., if your modified port directory is
 	called <filename>superedit</filename> and the original is in our tree
-	as <filename>superedit.bak</filename>, then send us the result of
+	as <filename>superedit.bak</filename>, then save the result of
 	<command>diff -ruN superedit.bak superedit</command>).  Either
 	unified or context diff is fine, but port committers generally
 	prefer unified diffs.  Note the use of the <literal>-N</literal>
 	option&mdash;this is the accepted way to force diff to properly
 	deal with the case of new files being added or old files being
-	deleted.</para>
+	deleted.  Before sending us the diff, please examine the
+	output to make sure all the changes make sense.</para>
 
-      <para>Please examine
+      <para> The best way to
-	the output to make sure all the changes make sense.  The best way to
 	send us the diff is by including it via &man.send-pr.1; (category
-	<literal>ports</literal>).  If you are the maintainer for the port,
+	<literal>ports</literal>).  If you are going to be the maintainer for the port,
 	be sure to put <literal>[maintainer update]</literal> at the beginning
 	of your synopsis line and/or set the <quote>Class</quote> of your PR
 	to <literal>maintainer-update</literal>.  Please mention any added or