[PATCH] backout: make help more explicit about what backout does

[Jonathan Nieder]

# HG changeset patch
# User Jonathan Nieder <jrnieder at gmail.com>
# Date 1296633712 21600
# Node ID 91804c80761f531f6b5eac52af7c8b9e6f9cd32f
# Parent  6bf8d48bec8e1ab2e0462ce14a914d06e64f7117
backout: make help more explicit about what backout does

The help for backout explains:

    The backout command merges the reverse effect of the reverted
    changeset into the working directory.

Unfortunately, that does not make it obvious to a newcomer what the
backout command does.  Since it performs a 3-way merge, what is the
common ancestor?  Will the result be automatically committed?  What is
this reverted changeset --- is it the rev passed with -r on the
command line or its inverse?

So try to clarify the description, avoiding jargon and being
explicit about what happens from the user's perspective.

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -204,24 +204,20 @@
 def backout(ui, repo, node=None, rev=None, **opts):
     '''reverse effect of earlier changeset
 
-    The backout command merges the reverse effect of the reverted
-    changeset into the working directory.
-
-    With the --merge option, it first commits the reverted changes
-    as a new changeset. This new changeset is a child of the reverted
-    changeset.
-    The --merge option remembers the parent of the working directory
-    before starting the backout, then merges the new head with that
-    changeset afterwards.
-    This will result in an explicit merge in the history.
-
-    If you backout a changeset other than the original parent of the
-    working directory, the result of this merge is not committed,
-    as with a normal merge. Otherwise, no merge is needed and the
-    commit is automatic.
-
-    Note that the default behavior (without --merge) has changed in
-    version 1.7. To restore the previous default behavior, use
+    Prepare a new changeset with the effect of REV undone in the
+    current working directory.
+
+    If REV is the tip, then this changeset is committed automatically.
+
+    Otherwise, a merge was necessary, so you should inspect the result
+    and then commit it.
+    If the --merge option is supplied, the next commit will have two
+    parents: the old parent of the working directory and a child
+    of REV that simply undoes REV.  Otherwise, the next commit will
+    have one parent, maintaining a linear history.
+
+    Before version 1.7, the default behavior (without --merge) was
+    different. To restore the previous default behavior, use
     :hg:`backout --merge` and then :hg:`update --clean .` to get rid of
     the ongoing merge.