[svn] Explained what patches are. Added more information about the use

of CVS.

PATCHES

@@ -1,65 +1,95 @@
 * Guidelines for patch submissions.
 ===================================
 
+** What is a patch?
+-------------------
+
+A patch file, also known as a "diff", is a textual representation of
+changes to source code.  Patches are readable enough to be reviewed by
+humans and at the same time regular enough to be processed by
+programs.  The `patch' utility is used to change the source code in
+the manner that the patch describes, this being called "applying" the
+patch.  Patches work even on files that have been modified
+independently of the modifications in the patch, as long as those
+other changes do not conflict with the patch.
+
+Because of these properties, patches are the preferred means of
+distributing the changes to a free software project.  If you have made
+a change to Wget and would like to contribute it, you will need to
+create a patch and send it to the developers; please read on.
+
 ** Where to send the patches.
 -----------------------------
 
 Patches intended to be applied to Wget should be mailed to
 <wget-patches@sunsite.dk>.  Each patch will be reviewed by the
 developers, and will be acked and added to the distribution, or
-rejected with an explanation.
+rejected with an explanation.  Unfortunately, the developers are often
+busy with their day jobs, so the review process can take a while.
 
 If you want to discuss your patch with the community of Wget users and
-developers, it is OK to send it to the general list at
+developers, it is OK to send it to the main list at <wget@sunsite.dk>.
-<wget@sunsite.dk>.  If the patch is really huge (more than 100K or
+If the patch is really huge (more than 100K or so), you may want to
-so), you may want to put it on the web and post the URL.
+put it on the web and post the URL.
 
 EVERY patch should be accompanied by an explanation of what the patch
-changes, and why the change is necessary.  The explanation need not be
+changes, and why the change is desirable or necessary.  The
-long, but please don't just send a patch without any text.
+explanation need not be long, but please don't just send a patch
+without any accompanying text.
 
 Normally, a patch can be just inserted into the message, after the
 explanation and the ChangeLog entry.  However, if your mail composer
-or gateway is inclined to munge patches, e.g. by line-wrapping them,
+or gateway is inclined to munge patches, e.g. by wrapping long lines,
 please send them out as a MIME attachment.  It is important that the
-patch survives the travel so that we can feed it to the `patch'
+patch survives the travel unchanged so that we can feed it to the
-utility after reviewing it.
+`patch' utility after reviewing it.
 
 ** How to create patches.
 -------------------------
 
-First, make sure you get the latest version of the source.  This is
+First, please make sure that you are working with the latest version
-normally the latest release.  If you're adding a new feature, or
+of the source -- changing obsolete code is a waste of time.  Working
-changing the code in some major way, you might want to download the
+on the latest release is acceptable in most cases, but it is better
-latest sources from the CVS server.  This procedure is described at
+yet to download the very latest sources from the public CVS server and
-<http://sunsite.dk/wget/>.
+work on those.  The web page at <http://sunsite.dk/wget/> explains
+what CVS is and how to check out Wget's source code from the public
+repository.
 
-Patches are created using the `diff' utility.  When making patches,
+Patches are created using the `diff' program.  When making patches,
 please use the `-u' option, or if your diff doesn't support it, `-c'.
-Using ordinary (context-free) diffs are notoriously prone to error,
+Ordinary (context-free) diffs are notoriously prone to errors, since
-since line numbers tend to change when others make changes to the same
+line numbers tend to change when others make changes to the same
 source file.
 
-An example of the `diff' usage:
+In the general case, `diff' is used like this:
 
-    diff -u OLDFILE NEWFILE
+    diff -u ORIGFILE CHANGEDFILE > patch.txt
-
-    -or-
-
-    diff -c OLDFILE NEWFILE
 
 Also, it is helpful if you create the patch in the top level of
-the Wget source directory:
+the Wget source directory.  For example:
 
-    $ cp src/http.c src/http.c.orig
+    cp src/http.c src/http.c.orig
-    ...hack, hack, hack....
+    ... modify src/http.c ....
-    $ diff -u src/http.c.orig src/http.c
+    diff -u src/http.c.orig src/http.c > patch.txt
 
-If your patch changes more than one file, the output of all the diff
+If your patch changes more than one file, feel free to simply
-invocations should be concatenated to form a single patch.
+concatenate the diffs of different files into a large diff:
-Alternatively, you can use the `-r' option to compare entire
+
-directories.  If you do that, be careful not to include the
+    (diff -u foo.orig foo; diff -u bar.orig bar) > patch.txt
-differences to automatically generated files, such as `.info*'.
+
+The alternative is to leave the unchanged source lying around and use
+the `-r' option to compare entire directories:
+
+    diff -ru wget-1.9.orig wget-1.9 > patch.txt
+
+If you do that, please be careful not to include the differences to
+automatically generated files, such as `.info*'.
+
+If you are using CVS, generating diffs is much simpler -- after
+changing the files, all you need to do is run the following command
+from Wget's top-level directory:
+
+    cvs diff -u > patch.txt
 
 If you run on Windows and don't have `diff' handy, please get one.
 It's extremely hard to review changes to files unless they're in the
@@ -80,12 +110,13 @@ Wget abides by the GNU coding standards, available at:
 
     http://www.gnu.org/prep/standards.html
 
-To me the most important single point in that entire document is "no
+I consider perhaps the most important single point in that entire
-arbitrary limits".  Even when Wget's coding is less than exemplary, it
+document to be the "no arbitrary limits" rule.  Even where Wget's
-respects that rule.  There should be no exceptions.
+coding is less than exemplary, it respects that rule.  There should be
+no exceptions.
 
 Here is a short recap of the GNU formatting and naming conventions,
-borrowed from XEmacs:
+partly borrowed from XEmacs:
 
   * Put a space after every comma.
 
@@ -120,11 +151,11 @@ borrowed from XEmacs:
 --------------------
 
 Each patch should be accompanied by an update to the appropriate
-ChangeLog file.  Please don't mail patches to ChangeLog because they
+ChangeLog file.  Please don't mail diffs of ChangeLog files because
-have an extremely high rate of failure; just mail us the new part of
+they have an extremely high rate of failure; just mail us the new
-the ChangeLog you added.  Patches without a ChangeLog entry will be
+entries you added to the ChangeLog.  Patches without a ChangeLog entry
-accepted, but this creates additional work for the maintainers, so
+will be accepted, but this creates additional work for the
-please do write the ChangeLog entries.
+maintainers, so please do take the time to write one.
 
 Guidelines for writing ChangeLog entries are also governed by the GNU
 coding standards, under the "Change Logs" section.