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

[Jonathan Nieder]

# HG changeset patch
# User Jonathan Nieder <jrnieder at gmail.com>
# Date 1296692409 21600
# Node ID d2f1fa1b002f11e972c11434a8c9414ad53bd523
# 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.

Thanks to Gilles Moris and timeless for help.

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -204,26 +204,24 @@
 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
-    :hg:`backout --merge` and then :hg:`update --clean .` to get rid of
-    the ongoing merge.
+    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, hg needs to merge the changes and you can inspect
+    them before committing.
+    By default, the pending changeset will have one parent,
+    maintaining a linear history.
+
+    With --merge, the next commit will have two parents: the old
+    parent of the working directory and a child of REV that simply
+    undoes REV.
+
+    Before version 1.7, the default behavior was equivalent to
+    specifying --merge followed by :hg:`update --clean .` to cancel
+    the merge and leave the child of REV as a head to be merged
+    separately.
 
     See :hg:`help dates` for a list of formats valid for -d/--date.