igor -Ry and some other rewording and fixes.

Differential Revision:	https://reviews.freebsd.org/D650
Reviewed by:	wblock
Sponsored by:	Absolight

1 files changed, 29 insertions, 25 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
index 3e08ed34fb..992d4bce96 100644
--- a/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
@@ -20,7 +20,7 @@
     <filename>/usr/ports/distfiles</filename>.</para>
 
   <note>
-    <para>The following steps assume that the software compiled
+    <para>These steps assume that the software compiled
       out-of-the-box.  In other words, absolutely no changes were
       required for the application to work on a &os; system.  If
       anything had to be changed, refer to <xref
@@ -96,11 +96,11 @@ COMMENT=	Cat chasing a mouse all over the screen
 	<para>This is <emphasis>not</emphasis> a manual or an
 	  in-depth description on how to use or compile the port!
 	  <emphasis>Please be careful when copying from the
-	  <filename>README</filename> or manpage</emphasis>; too
+	  <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, which looks particularly bad with monospaced
-	  fonts).</para>
+	  are in an awkward format.  For example, manpages have
+	  justified spacing, which looks particularly bad with
+	  monospaced fonts.</para>
       </note>
 
       <para>A well-written <filename>pkg-descr</filename> describes
@@ -116,7 +116,7 @@ COMMENT=	Cat chasing a mouse all over the screen
 	<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
+	URI is the root of the website or directory, it must be
 	terminated with a slash.</para>
 
       <note>
@@ -125,8 +125,8 @@ COMMENT=	Cat chasing a mouse all over the screen
 	  moved, was renamed, or is hosted elsewhere.</para>
       </note>
 
-      <para>The following example shows how the
-	<filename>pkg-descr</filename> should look:</para>
+      <para>This example shows how
+	<filename>pkg-descr</filename> looks:</para>
 
       <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
 the screen.
@@ -182,8 +182,8 @@ lib/X11/oneko/mouse.xpm
 	<varname>PLIST_DIRS</varname>, respectively, within the
 	port's <filename>Makefile</filename>.  For instance, we
 	could get along without <filename>pkg-plist</filename> in
-	the above <filename>oneko</filename> port by adding the
-	following lines to the <filename>Makefile</filename>:</para>
+	the above <filename>oneko</filename> port by adding these
+	lines to the <filename>Makefile</filename>:</para>
 
       <programlisting>PLIST_FILES=	bin/oneko \
 		man/man1/oneko.1.gz \
@@ -193,12 +193,12 @@ lib/X11/oneko/mouse.xpm
 		lib/X11/oneko/mouse.xpm
 PLIST_DIRS=	lib/X11/oneko</programlisting>
 
-      <para>Of course, <varname>PLIST_DIRS</varname> should be left
-	unset if a port installs no directories of its own.</para>
+      <para>Of course, <varname>PLIST_DIRS</varname> does not need to
+	be set if a port installs no directories of its own.</para>
 
       <note>
 	<para>Several ports can share a common directory.  In that
-	  case, <varname>PLIST_DIRS</varname> should be replaced by
+	  case, <varname>PLIST_DIRS</varname> must be replaced by
 	  <varname>PLIST_DIRSTRY</varname> so that the directory is
 	  removed only if empty, otherwise it is silently ignored.
 	  <varname>PLIST_DIRS</varname> and
@@ -351,26 +351,30 @@ PLIST_DIRS=	lib/X11/oneko</programlisting>
       is located, and then type:
       <command>shar `find oneko` &gt; oneko.shar</command></para>
 
+    <!-- The link here is wrong, but, I have no idea where
+    to point it now, so commenting the whole paragraph.
+
     <para>Include <filename>oneko.shar</filename> in a bug
-      report and send it with &man.send-pr.1;.  See <link
+      report and submit it.  See <link
 	xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
 	Reports and General Commentary</link> for more information
-      about &man.send-pr.1;.</para>
+      submitting problem reports.</para> -->
 
-    <para>Classify the bug report as Category
-      <literal>ports</literal> and Class
-      <literal>change-request</literal>.  Do <emphasis>not</emphasis>
-      mark the report <literal>confidential</literal>!  Add a short
+    <para>To submit <filename>oneko.shar</filename>, use the <link
+	xlink:href="https://bugs.freebsd.org/submit/">bug submit
+	form</link> (category <literal>Ports Tree</literal>).
+      Add a short
       description of the program to the Description field of the PR
-      (perhaps a short version of the <varname>COMMENT</varname>), and
-      add the <filename>.shar</filename> file to the Fix field.</para>
+      (perhaps a short version of <varname>COMMENT</varname>), and
+      don't forget to add <filename>oneko.shar</filename> as an
+      attachment.</para>
 
     <note>
-      <para>Giving a good description in the synopsis of the problem
+      <para>Giving a good description in the summary of the problem
 	report makes the work of port committers a lot easier.  We
 	prefer something like <quote>New port:
-	  &lt;category&gt;/&lt;portname&gt; &lt;short description of
-	  the port&gt;</quote> for new ports.  Using this
+	  <replaceable>category</replaceable>/<replaceable>portname</replaceable> <replaceable>short description of
+	    the port</replaceable></quote> for new ports.  Using this
 	scheme makes it easier and faster to begin the work of
 	committing the new port.</para>
     </note>
@@ -388,7 +392,7 @@ PLIST_DIRS=	lib/X11/oneko</programlisting>
 	xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"></link>.</para>
 
     <para>After looking at the new port, we will reply if necessary,
-      and put it in the tree.  Your name will also be added to the
+      and commit it to the tree.  The submitter's name will also be added to the
       list of <link
 	xlink:href="&url.articles.contributors;/contrib-additional.html">Additional
 	&os; Contributors</link> and other files.</para>