More typo and markup fixes.

Submitted by:	keramidas.

en_US.ISO8859-1/articles/problem-reports/article.sgml

@@ -38,11 +38,12 @@ FreeBSD Entities//EN"> %freebsd;
     <para>One of the most frustrating experiences one can have as a
       software user is to submit a problem report only to have it
       summarily closed with a terse and unhelpful explanation like
-      "not a bug" or "bogus PR".  Similarly, one of the most
+      <quote>not a bug</quote> or <quote>bogus PR</quote>.  Similarly,
-      frustrating experiences as a software developer is to be flooded
+      one of the most frustrating experiences as a software developer
-      with problem reports that are not really problem reports but
+      is to be flooded with problem reports that are not really
-      requests for support, or that contain little or no information
+      problem reports but requests for support, or that contain little
-      about what the problem is and how to reproduce it.</para>
+      or no information about what the problem is and how to reproduce
+      it.</para>
 
     <para>This document attempts to describe how to write good problem
       reports.  What, you ask, is a good problem report?  Well, to go
@@ -56,8 +57,8 @@ FreeBSD Entities//EN"> %freebsd;
 
     <para>Note that this article is organized thematically, not
       chronologically, so you should read through the entire document
-      before submitting a PR, rather than treat it as a step-by-step
+      before submitting a problem report, rather than treat it as a
-      tutorial.</para>
+      step-by-step tutorial.</para>
   </sect1>
 
   <sect1 id="pr-when">
@@ -65,31 +66,31 @@ FreeBSD Entities//EN"> %freebsd;
 
     <para>There are many types of problems, and not all of them should
       engender a problem report.  Of course, nobody is perfect, and
-      there will be times when you are convinced you've found a bug in
+      there will be times when you are convinced you have found a bug
-      a program when in fact you've misunderstood the syntax for a
+      in a program when in fact you have misunderstood the syntax for
-      command or made a typo in a configuration file (though that in
+      a command or made a typo in a configuration file (though that in
       itself may sometimes be indicative of poor documentation or poor
       error handling in the application).  There are still many cases
       where submitting a problem report is clearly not the right
       course of action, and will only serve to frustrate you and the
       developers.  Conversely, there are cases where it might be
       appropriate to submit a problem report about something else than
-      a bug &mdash; an enhancement or a feature request, for
+      a bug&mdash;an enhancement or a feature request, for
       instance.</para>
 
-    <para>So how do you determine what's a bug and what is not?  As a
+    <para>So how do you determine what is a bug and what is not?  As a
       simple rule of thumb your problem is <emphasis>not</emphasis> a
       bug if it can be expressed as a question (usually of the form
-      "How do I do X?" or "Where can I find Y?").  It's not always
+      <quote>How do I do X?</quote> or <quote>Where can I find
-      quite so black and white, but the question rule covers a large
+      Y?</quote>).  It is not always quite so black and white, but the
-      majority of cases.</para>
+      question rule covers a large majority of cases.</para>
 
     <para>Some cases where it may be appropriate to submit a problem
       report about something that is not a bug are:</para>
 
     <itemizedlist>
       <listitem>
-        <para>Requests for feature enhancments.  It is generally a
+        <para>Requests for feature enhancements.  It is generally a
           good idea to air these on the mailing lists before
           submitting a problem report.</para>
       </listitem>
@@ -109,14 +110,14 @@ FreeBSD Entities//EN"> %freebsd;
       that will annoy a developer more than receiving a problem report
       about a bug she's already fixed.</para>
 
-    <para>Finally, a bug that can't be reproduced can rarely be fixed.
+    <para>Finally, a bug that can not be reproduced can rarely be
-      If the bug only occurred once and you can't reproduce it, and it
+      fixed.  If the bug only occurred once and you can not reproduce
-      doesn't seem to happen to anybody else, chances are none of the
+      it, and it does not seem to happen to anybody else, chances are
-      developers will be able to reproduce it or figure out what's
+      none of the developers will be able to reproduce it or figure
-      wrong.  That doesn't mean it didn't happen, but it does mean
+      out what's wrong.  That does not mean it did not happen, but it
-      that the chances of your problem report ever leading to a bug
+      does mean that the chances of your problem report ever leading
-      fix are very slim, and you should consider letting the matter
+      to a bug fix are very slim, and you should consider letting the
-      drop.</para>
+      matter drop.</para>
   </sect1>
 
   <sect1 id="pr-prep">
@@ -124,11 +125,11 @@ FreeBSD Entities//EN"> %freebsd;
 
     <para>A good rule to follow is to always do a background search
       before submitting a problem report.  Maybe your problem has
-      already been reported; maybe it's being discussed on the mailing
+      already been reported; maybe it is being discussed on the
-      lists, or recently was; it may even already be fixed in a newer
+      mailing lists, or recently was; it may even already be fixed in
-      version than what you're running.  You should therefore check
+      a newer version than what you are running.  You should therefore
-      all the obvious places before submitting your PR.  For FreeBSD,
+      check all the obvious places before submitting your problem
-      this means:</para>
+      report.  For FreeBSD, this means:</para>
 
     <itemizedlist>
       <listitem>
@@ -136,24 +137,24 @@ FreeBSD Entities//EN"> %freebsd;
       </listitem>
 
       <listitem>
-        <para>The mailing lists &mdash; if you're not subscribed, use
+        <para>The mailing lists&mdash;if you're not subscribed, use
           the searchable archives on the FreeBSD web site.  If your
-          problem hasn't been discussed on the lists, you might try
+          problem has not been discussed on the lists, you might try
           posting a message about it and waiting a few days to see if
-          someone can spot something you've overlooked.</para>
+          someone can spot something you have overlooked.</para>
       </listitem>
 
       <listitem>
-        <para>Optionally, the entire web &mdash; use your favorite
+        <para>Optionally, the entire web&mdash;use your favorite
           search engine to locate any references to your problem.  You
           may even get hits from archived mailing lists or newsgroups
-          you didn't know of or hadn't thought to search
+          you did not know of or had not thought to search
           through.</para>
       </listitem>
 
       <listitem>
         <para>Finally, the FreeBSD PR database.  Unless your problem
-          is recent or obscure, there's a fair chance it's already
+          is recent or obscure, there is a fair chance it has already
           been reported.</para>
       </listitem>
     </itemizedlist>
@@ -169,12 +170,12 @@ FreeBSD Entities//EN"> %freebsd;
       problem may lie in how the software was ported to FreeBSD; the
       second is if the original author has already fixed the bug and
       released a patch or a new version of his software, and the
-      FreeBSD port hasn't been updated yet.</para>
+      FreeBSD port has not been updated yet.</para>
 
     <para>The second catch is that FreeBSD's bug tracking system sorts
       problem reports according to the category the originator
       selected.  Therefore, if you select the wrong category when you
-      submit your problem report, there's a good chance that it will
+      submit your problem report, there is a good chance that it will
       go unnoticed for a while, until someone re-categorizes
       it.</para>
   </sect1>
@@ -182,10 +183,10 @@ FreeBSD Entities//EN"> %freebsd;
   <sect1 id="pr-writing">
     <title>Writing the problem report</title>
 
-    <para>Now that you've decided that your issue merits a problem
+    <para>Now that you have decided that your issue merits a problem
-      report, and that it's a FreeBSD problem, it's time to write the
+      report, and that it is a FreeBSD problem, it is time to write
-      actual PR.  Make sure your <envar>VISUAL</envar> (or
+      the actual problem report.  Make sure your <envar>VISUAL</envar>
-      <envar>EDITOR</envar> if <envar>VISUAL</envar> is not set)
+      (or <envar>EDITOR</envar> if <envar>VISUAL</envar> is not set)
       environment variable is set to something sensible, and run
       &man.send-pr.1;.</para>
 
@@ -198,13 +199,13 @@ FreeBSD Entities//EN"> %freebsd;
         name of the file proper, without the path).  Just use the
         <option>-a</option> command-line option to specify the names
         of the files you wish to attach:</para>
-	
+
 <screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput>
 </screen>
 
       <para>Don't worry about binary files; they will be automatically
         encoded so as not to upset your mail agent.</para>
-	
+
       <para>If you attach a patch, make sure you use the
         <option>-c</option> or <option>-u</option> option to
         &man.diff.1; to create a context or unified diff, and make
@@ -218,15 +219,15 @@ FreeBSD Entities//EN"> %freebsd;
 
       <para>The template consists of a list of fields, some of which
         are pre-filled, and some of which have comments explaining
-        their purpose or listing acceptable values.  Don't worry about
+        their purpose or listing acceptable values.  Do not worry
-        the comments; they'll be removed automatically if you don't
+        about the comments; they will be removed automatically if you
-        modify them or remove them yourself.</para>
+        do not modify them or remove them yourself.</para>
 
       <para>At the top of the template, below the
         <literal>SEND-PR:</literal> lines, are the email headers.  You
-        don't normally need to modify these, unless you're sending the
+        do not normally need to modify these, unless you are sending
-        PR from a machine or account that can send but not receive
+        the problem report from a machine or account that can send but
-        mail, in which case you'll want to set the
+        not receive mail, in which case you will want to set the
         <literal>From:</literal> and <literal>Reply-To:</literal> to
         your real email address.  You may also want to send yourself
         (or someone else) a carbon copy of the problem report by
@@ -258,17 +259,18 @@ FreeBSD Entities//EN"> %freebsd;
 	<listitem>
 	  <para><emphasis>Confidential:</emphasis> This is prefilled
   	    to <literal>no</literal>; changing it makes no sense as
-  	    there is no such thing as a confidential FreeBSD PR
+  	    there is no such thing as a confidential FreeBSD problem
-  	    &mdash; the PR database is distributed worldwide by
+  	    report&mdash;the PR database is distributed worldwide by
   	    CVSup.</para>
 	</listitem>
 
 	<listitem>
 	  <para><emphasis>Synopsis:</emphasis> Fill this out with a
  	    short and accurate description of the problem.  The
- 	    synopsis is used as the subject of the PR email, and is
+ 	    synopsis is used as the subject of the problem report
- 	    used in PR listings and summaries; problem reports with
+ 	    email, and is used in problem report listings and
- 	    obscure synopses tend to get ignored.</para>
+ 	    summaries; problem reports with obscure synopses tend to
+ 	    get ignored.</para>
 
 	  <para>If your problem report includes a patch, please have
  	    the synopsis start with <literal>[PATCH]</literal>.</para>
@@ -278,12 +280,12 @@ FreeBSD Entities//EN"> %freebsd;
 	  <para><emphasis>Severity:</emphasis> One of
   	    <literal>non-critical</literal>,
   	    <literal>serious</literal> or
-  	    <literal>critical</literal>.  Don't overreact; refrain
+  	    <literal>critical</literal>.  Do not overreact; refrain
   	    from labeling your problem <literal>critical</literal>
   	    unless it really is (e.g. root exploit, easily
   	    reproducible panic).  Developers tend to ignore this and
-  	    the next field, precisely because PR submitters tend to
+  	    the next field, precisely because problem report
-  	    overrate their problems.</para>
+  	    submitters tend to overrate their problems.</para>
 	</listitem>
 
 	<listitem>
@@ -291,7 +293,7 @@ FreeBSD Entities//EN"> %freebsd;
   	    <literal>low</literal>, <literal>medium</literal> or
   	    <literal>high</literal>.  See above.</para>
 	</listitem>
-	
+
 	<listitem>
 	  <para><emphasis>Category:</emphasis> Choose one of the
 	    following:</para>
@@ -337,7 +339,7 @@ FreeBSD Entities//EN"> %freebsd;
 	    </listitem>
 
 	    <listitem>
-	      <para><literal>misc:</literal> anything that doesn't fit
+	      <para><literal>misc:</literal> anything that does not fit
 	        in any of the other categories.</para>
 	    </listitem>
 	
@@ -384,13 +386,13 @@ FreeBSD Entities//EN"> %freebsd;
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
-	
+
 	<listitem>
 	  <para><emphasis>Release:</emphasis> The version of FreeBSD
 	    that you are running.  This is filled out automatically by
 	    &man.send-pr.1; and need only be changed if you are
-	    sending a PR from a different system than the one that
+	    sending a problem report from a different system than the
-	    exhibits the problem.</para>
+	    one that exhibits the problem.</para>
 	</listitem>
       </itemizedlist>
 
@@ -404,12 +406,12 @@ FreeBSD Entities//EN"> %freebsd;
             operating system version, the version of the specific
             program or file that contains the problem, and any other
             relevant items such as system configuration, other
-            installed software that influences the problem, etc.
+            installed software that influences the problem,
-            &mdash; quite simply everything a developer needs to know
+            etc.&mdash;quite simply everything a developer needs to
-            to reconstruct the environment in which the problem
+            know to reconstruct the environment in which the problem
             occurs.</para>
 	</listitem>
-	
+
 	<listitem>
 	  <para><emphasis>Description:</emphasis> A complete and
 	    accurate description of the problem you are experiencing.
@@ -418,30 +420,30 @@ FreeBSD Entities//EN"> %freebsd;
 	    it may mislead a developer into making incorrect
 	    assumptions about the problem.</para>
 	</listitem>
-	
+
 	<listitem>
 	  <para><emphasis>How-To-Repeat:</emphasis> A summary of the
 	    actions you need to take to reproduce the problem.</para>
 	</listitem>
-	
+
 	<listitem>
 	  <para><emphasis>Fix:</emphasis> Preferably a patch, or at
 	    least a workaround (which not only helps other people with
 	    the same problem work around it, but may also help a
 	    developer understand the cause for the problem), but if
-	    you don't have any firm ideas for either, it's better to
+	    you do not have any firm ideas for either, it's better to
 	    leave this field blank than to speculate.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
-      <title>Sending off the PR</title>
+      <title>Sending off the problem report</title>
 
-      <para>Once you're done filling out the template, have saved it,
+      <para>Once you are done filling out the template, have saved it,
         and exit your editor, &man.send-pr.1; will prompt you with
         <prompt>s)end, e)dit or a)bort?</prompt>.  You can then hit
-        <userinput>s</userinput> to go ahead and submit the PR,
+        <userinput>s</userinput> to go ahead and submit the problem report,
         <userinput>e</userinput> to restart the editor and make
         further modifications, or <userinput>a</userinput> to abort.
         If you choose the latter, your problem report will remain on
@@ -450,9 +452,8 @@ FreeBSD Entities//EN"> %freebsd;
         transfer it to a system with better net connectivity, before
         sending it with the <option>-f</option> to
         &man.send-pr.1;:</para>
-	
+
-<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput>
+<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>
-</screen>
 
       <para>This will read the specified file, validate the contents,
         strip comments and send it off.</para>
@@ -463,27 +464,26 @@ FreeBSD Entities//EN"> %freebsd;
   <sect1 id="pr-followup">
     <title>Follow-up</title>
 
-    <para>Once your problem report has been filed, you'll receive a
+    <para>Once your problem report has been filed, you will receive a
       confirmation by email which will include the tracking number
-      that was assigned to your PR and a URL you can use to check its
+      that was assigned to your problem report and a URL you can use
-      status.  With a little luck, someone will take an interest in
+      to check its status.  With a little luck, someone will take an
-      your problem and try to address it, or, as the case may be,
+      interest in your problem and try to address it, or, as the case
-      explain why it's not a problem.  You'll be automatically
+      may be, explain why it is not a problem.  You will be
-      notified of any change of status, and you'll receive copies of
+      automatically notified of any change of status, and you will
-      any comments or patches someone may attach to your PR's audit
+      receive copies of any comments or patches someone may attach to
-      trail.</para>
+      your problem report's audit trail.</para>
 
     <para>If someone requests additional information from you, or you
-      remember or discover something you didn't mention in the initial
+      remember or discover something you did not mention in the
-      report, just mail it to <email>bug-followup@FreeBSD.org</email>,
+      initial report, just mail it to
-      making sure that the tracking number is included in the subject
+      <email>bug-followup@FreeBSD.org</email>, making sure that the
-      so the bug tracking system will know what problem report to
+      tracking number is included in the subject so the bug tracking
-      attach it to.</para>
+      system will know what problem report to attach it to.</para>
 
     <para>If the problem report remains open after the problem has
       gone away, just send a follow-up (in the manner prescribed
-      above) saying that the PR can be closed, and, if possible,
+      above) saying that the problem report can be closed, and, if
-      explaining how or when the problem was fixed.</para>
+      possible, explaining how or when the problem was fixed.</para>
   </sect1>
-
 </article>