igor -Ry and some other rewording and fixes.

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

en_US.ISO8859-1/books/porters-handbook/security/chapter.xml

@@ -40,8 +40,8 @@
       even notice the harm caused.  Third, exposing a vulnerable
       system often assists attackers to break into other systems that
       could not be compromised otherwise.  Therefore closing a
-      vulnerability alone is not enough: the audience should be
-      notified of it in most clear and comprehensive manner, which
+      vulnerability alone is not enough: notify the audience
+      of it in most clear and comprehensive manner, which
       will allow to evaluate the danger and take appropriate
       actions.</para>
   </sect1>
@@ -53,21 +53,21 @@
       vulnerability may initially appear in the original distribution
       or in the port files.  In the former case, the original software
       developer is likely to release a patch or a new version
-      instantly, and you will only need to update the port promptly
+      instantly.  Update the port promptly
       with respect to the author's fix.  If the fix is delayed for
-      some reason, you should either
+      some reason, either
       <link linkend="dads-noinstall">mark the port as
-      <varname>FORBIDDEN</varname></link> or introduce a patch file of
-      your own to the port.  In the case of a vulnerable port, just
-      fix the port as soon as possible.  In either case,
+      <varname>FORBIDDEN</varname></link> or introduce a patch file
+      to the port.  In the case of a vulnerable port, just
+      fix the port as soon as possible.  In either case, follow
       <link linkend="port-upgrading">the standard procedure for
-      submitting your change</link> should be followed unless you have
+      submitting changes</link> unless having
       rights to commit it directly to the ports tree.</para>
 
     <important>
       <para>Being a ports committer is not enough to commit to an
 	arbitrary port.  Remember that ports usually have maintainers,
-	whom you should respect.</para>
+	must be respected.</para>
     </important>
 
     <para>Please make sure that the port's revision is bumped as soon
@@ -75,11 +75,11 @@
       upgrade installed packages on a regular basis will see they need
       to run an update.  Besides, a new package will be built and
       distributed over FTP and WWW mirrors, replacing the vulnerable
-      one.  <varname>PORTREVISION</varname> should be bumped unless
+      one.  Bump <varname>PORTREVISION</varname> unless
       <varname>PORTVERSION</varname> has changed in the course of
-      correcting the vulnerability.  That is you should bump
-      <varname>PORTREVISION</varname> if you have added a patch file
-      to the port, but you should not if you have updated the port to
+      correcting the vulnerability.  That is, bump
+      <varname>PORTREVISION</varname> if adding a patch file
+      to the port, but do not bump it if updating the port to
       the latest software version and thus already touched
       <varname>PORTVERSION</varname>.  Please refer to the
       <link linkend="makefile-naming-revepoch">corresponding
@@ -95,9 +95,9 @@
       <para>A very important and urgent step to take as early after a
 	security vulnerability is discovered as possible is to notify
 	the community of port users about the jeopardy.  Such
-	notification serves two purposes.  First, should the danger be
+	notification serves two purposes.  First, if the danger is
 	really severe it will be wise to apply an instant workaround.
-	E.g., stop the affected network service or even deinstall the
+	For example, stop the affected network service or even deinstall the
 	port completely until the vulnerability is closed.  Second, a
 	lot of users tend to upgrade installed packages only
 	occasionally.  They will know from the notification that they
@@ -114,6 +114,7 @@
 	also monitor it for issues requiring their
 	intervention.</para>
 
+      <!-- XXX: Too much "you" in there -->
       <para>If you have committer rights you can update the VuXML
 	database by yourself.  So you will both help the Security
 	Officer Team and deliver the crucial information to the
@@ -129,10 +130,10 @@
 	inside the port <package role="port">security/vuxml</package>.
 	Therefore the file's full pathname will be
 	<filename>PORTSDIR/security/vuxml/vuln.xml</filename>.  Each
-	time you discover a security vulnerability in a port, please
-	add an entry for it to that file.  Until you are familiar with
-	VuXML, the best thing you can do is to find an existing entry
-	fitting your case, then copy it and use it as a
+	time a security vulnerability is discovered in a port, please
+	add an entry for it to that file.  Until familiar with
+	VuXML, the best thing to do is to find an existing entry
+	fitting the case at hand, then copy it and use it as a
 	template.</para>
     </sect2>
 
@@ -141,14 +142,14 @@
 
       <para>The full-blown <acronym>XML</acronym> format is complex,
 	and far beyond the scope of this book.  However, to gain basic
-	insight on the structure of a VuXML entry you need only the
-	notion of tags.  XML tag names are enclosed in angle brackets.
+	insight on the structure of a VuXML entry only the notion of
+	tags is needed.  XML tag names are enclosed in angle brackets.
 	Each opening &lt;tag&gt; must have a matching closing
 	&lt;/tag&gt;.  Tags may be nested.  If nesting, the inner tags
 	must be closed before the outer ones.  There is a hierarchy of
-	tags, i.e., more complex rules of nesting them.  This is
+	tags, that is, more complex rules of nesting them.  This is
 	similar to HTML.  The major difference is that XML is
-	e<emphasis>X</emphasis>tensible, i.e., based on defining
+	e<emphasis>X</emphasis>tensible, that is, based on defining
 	custom tags.  Due to its intrinsic structure XML puts
 	otherwise amorphous data into shape.  VuXML is particularly
 	tailored to mark up descriptions of security
@@ -206,18 +207,18 @@
 &lt;/vuln&gt;</programlisting>
 
       <para>The tag names are supposed to be self-explanatory so we
-	shall take a closer look only at fields you will need to fill
-	in by yourself:</para>
+	shall take a closer look only at fields which needs to be fill
+	in:</para>
 
       <calloutlist>
 	<callout arearefs="co-vx-vid">
 	  <para>This is the top-level tag of a VuXML entry.  It has a
 	    mandatory attribute, <literal>vid</literal>, specifying a
 	    universally unique identifier (UUID) for this entry (in
-	    quotes).  You should generate a UUID for each new VuXML
+	    quotes).  Generate a UUID for each new VuXML
 	    entry (and do not forget to substitute it for the template
-	    UUID unless you are writing the entry from scratch).  You
-	    can use &man.uuidgen.1; to generate a VuXML UUID.</para>
+	    UUID unless writing the entry from scratch).
+	    use &man.uuidgen.1; to generate a VuXML UUID.</para>
 	</callout>
 
 	<callout arearefs="co-vx-top">
@@ -234,10 +235,10 @@
 	    important build-time configuration options.</para>
 
 	  <important>
-	    <para>It is your responsibility to find all such related
+	    <para>It is the submitter's responsibility to find all such related
 	      packages when writing a VuXML entry.  Keep in mind that
-	      <literal>make search name=foo</literal> is your friend.
-	      The primary points to look for are as follows:</para>
+	      <literal>make search name=foo</literal> is helpful.
+	      The primary points to look for are:</para>
 
 	    <itemizedlist>
 	      <listitem>
@@ -269,8 +270,8 @@
 	    <literal>&lt;le&gt;</literal>,
 	    <literal>&lt;eq&gt;</literal>,
 	    <literal>&lt;ge&gt;</literal>, and
-	    <literal>&lt;gt&gt;</literal> elements.  The version
-	    ranges given should not overlap.</para>
+	    <literal>&lt;gt&gt;</literal> elements.  Check the version
+	    ranges given do not overlap.</para>
 
 	  <para>In a range specification, <literal>*</literal>
 	    (asterisk) denotes the smallest version number.  In
@@ -304,13 +305,13 @@
 	</callout>
 
 	<callout arearefs="co-vx-epo">
-	  <para>The version ranges should allow for
+	  <para>The version ranges have to allow for
 	    <varname>PORTEPOCH</varname> and
 	    <varname>PORTREVISION</varname> if applicable.  Please
 	    remember that according to the collation rules, a version
 	    with a non-zero <varname>PORTEPOCH</varname> is greater
 	    than any version without <varname>PORTEPOCH</varname>,
-	    e.g., <literal>3.0,1</literal> is greater than
+	    for example, <literal>3.0,1</literal> is greater than
 	    <literal>3.1</literal> or even than
 	    <literal>8.9</literal>.</para>
 	</callout>
@@ -318,7 +319,7 @@
 	<callout arearefs="co-vx-bdy">
 	  <para>This is a summary of the issue.  XHTML is used in this
 	    field.  At least enclosing <literal>&lt;p&gt;</literal>
-	    and <literal>&lt;/p&gt;</literal> should appear.  More
+	    and <literal>&lt;/p&gt;</literal> has to appear.  More
 	    complex mark-up may be used, but only for the sake of
 	    accuracy and clarity: No eye candy please.</para>
 	</callout>
@@ -337,7 +338,7 @@
 
 	<callout arearefs="co-vx-fpr">
 	  <para>This is a <link
-	      xlink:href="http://www.freebsd.org/support.html#gnats">&os;
+	      xlink:href="http://www.freebsd.org/support.html">&os;
 	      problem report</link>.</para>
 	</callout>
 
@@ -384,7 +385,7 @@
 	</callout>
 
 	<callout arearefs="co-vx-url">
-	  <para>This is a generic URL.  It should be used only if none
+	  <para>This is a generic URL.  Only it if none
 	    of the other reference categories apply.</para>
 	</callout>
 
@@ -401,37 +402,37 @@
 	<callout arearefs="co-vx-mod">
 	  <para>This is the date when any information in the entry was
 	    last modified (<replaceable>YYYY-MM-DD</replaceable>).
-	    New entries must not include this field.  It should be
-	    added upon editing an existing entry.</para>
+	    New entries must not include this field.  Add it when
+	    editing an existing entry.</para>
 	</callout>
       </calloutlist>
     </sect2>
 
     <sect2 xml:id="security-notify-vuxml-testing">
-      <title>Testing Your Changes to the VuXML Database</title>
+      <title>Testing Changes to the VuXML Database</title>
 
-      <para>Assume you just wrote or filled in an entry for a
+      <para>Assume a new entry for a
 	vulnerability in the package <literal>clamav</literal> that
 	has been fixed in version <literal>0.65_7</literal>.</para>
 
-      <para>As a prerequisite, you need to
+      <para>As a prerequisite,
 	<emphasis>install</emphasis> fresh versions of the ports
 	<package role="port">ports-mgmt/portaudit</package>,
 	<package role="port">ports-mgmt/portaudit-db</package>, and
 	<package role="port">security/vuxml</package>.</para>
 
       <note>
-	<para>To run <command>packaudit</command> you must have
+	<para>The user running <command>packaudit</command> must have
 	  permission to write to its <filename>DATABASEDIR</filename>,
 	  typically <filename>/var/db/portaudit</filename>.</para>
 
-	<para>To use a different directory set the
-	  <filename>DATABASEDIR</filename> environment variable to a
+	<para>To use a different directory, set the
+	  <varname>DATABASEDIR</varname> environment variable to a
 	  different location.</para>
 
-	<para>If you are working in a directory other than
-	  <filename>${PORTSDIR}/security/vuxml</filename> set the
-	  <filename>VUXMLDIR</filename> environment variable to the
+	<para>If working in a directory other than
+	  <filename>${PORTSDIR}/security/vuxml</filename>, set the
+	  <varname>VUXMLDIR</varname> environment variable to the
 	  directory where <filename>vuln.xml</filename> is
 	  located.</para>
       </note>
@@ -444,18 +445,18 @@
       <screen>&prompt.user; <userinput>packaudit</userinput>
 &prompt.user; <userinput>portaudit clamav-0.65_6</userinput></screen>
 
-      <para>If there is none found, you have the green light to add a
+      <para>If there is none found, add a
 	new entry for this vulnerability.</para>
 
       <screen>&prompt.user; <userinput>cd ${PORTSDIR}/security/vuxml</userinput>
 &prompt.user; <userinput>make newentry</userinput></screen>
 
-      <para>When you are done verify its syntax and formatting.</para>
+      <para>Verify its syntax and formatting:</para>
 
       <screen>&prompt.user; <userinput>make validate</userinput></screen>
 
       <note>
-	<para>You will need at least one of the following packages
+	<para>At least one of these packages needs to be
 	  installed: <package role="port">textproc/libxml2</package>,
 	  <package role="port">textproc/jade</package>.</para>
       </note>
@@ -466,8 +467,8 @@
       <screen>&prompt.user; <userinput>packaudit</userinput></screen>
 
       <para>To verify that the <literal>&lt;affected&gt;</literal>
-	section of your entry will match correct package(s), issue the
-	following command:</para>
+	section of the entry will match correct package(s), issue this
+	command:</para>
 
       <screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r <replaceable>uuid</replaceable></userinput></screen>
 
@@ -476,11 +477,11 @@
 	  understanding of the command syntax.</para>
       </note>
 
-      <para>Make sure that your entry produces no spurious matches in
+      <para>Make sure that the entry produces no spurious matches in
 	the output.</para>
 
       <para>Now check whether the right package versions are matched
-	by your entry:</para>
+	by the entry:</para>
 
       <screen>&prompt.user; <userinput>portaudit clamav-0.65_6 clamav-0.65_7</userinput>
 Affected package: clamav-0.65_6 (matched by clamav&lt;0.65_7)
@@ -489,8 +490,8 @@ Reference: &lt;http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00
 
 1 problem(s) found.</screen>
 
-      <para>The former version should match while the latter one
-	should not.</para>
+      <para>The former version matches while the latter one
+	does not.</para>
 
       <para>Finally, verify whether the web page generated from the
 	VuXML database looks like expected:</para>