[PATCH] resolve: updated help documentation for improved clarity

[Mark Edgington]

The present resolve help text is a bit cumbersome, and users can
easily overlook / miss that the command can be used for re-merging
files (using whatever automated merge-tool is set up in one's hg
config).  This patch is an attempt to improve the readability/clarity
of the help text.  Feel free to modify it as needed...

# HG changeset patch
# User Mark Edgington <edgimar at gmail.com>
# Date 1281646102 -7200
# Node ID d7366882563afded86866f267918307a7cda9817
# Parent  fda0e478fb7945b15110738885b8f54bcf2ff576
resolve: updated help documentation for improved clarity

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -2947,31 +2947,36 @@
         wlock.release()

 def resolve(ui, repo, *pats, **opts):
-    """various operations to help finish a merge
-
-    This command includes several actions that are often useful while
-    performing a merge, after running ``merge`` but before running
-    ``commit``.  (It is only meaningful if your working directory has
-    two parents.)  It is most relevant for merges with unresolved
-    conflicts, which are typically a result of non-interactive merging with
-    ``internal:merge`` or a command-line merge tool like ``diff3``.
-
-    The available actions are:
-
-      1) list files that were merged with conflicts (U, for unresolved)
-         and without conflicts (R, for resolved): ``hg resolve -l``
-         (this is like ``status`` for merges)
-      2) record that you have resolved conflicts in certain files:
-         ``hg resolve -m [file ...]`` (default: mark all unresolved files)
-      3) forget that you have resolved conflicts in certain files:
-         ``hg resolve -u [file ...]`` (default: unmark all resolved files)
-      4) discard your current attempt(s) at resolving conflicts and
-         restart the merge from scratch: ``hg resolve file...``
-         (or ``-a`` for all unresolved files)
-
-    Note that Mercurial will not let you commit files with unresolved merge
-    conflicts.  You must use ``hg resolve -m ...`` before you can commit
-    after a conflicting merge.
+    """redo merges of unresolved files, or set/view the merge status of files
+
+    Merges with unresolved conflicts are often the result of
+    non-interactive merging using the "internal:merge" hgrc setting,
+    or a command-line merge tool like "diff3".  The resolve command is
+    used to manage the files involved in a merge, after ``hg merge``
+    has been run, and before ``hg commit`` is run (i.e. the working
+    directory must have two parents).
+
+    The resolve command can be used in the following ways:
+
+      'hg resolve <-a | FILE...>':  attempt to re-merge the specified
+    files, discarding any previous merge attempts.  Re-merging is not
+    performed for files already marked as resolved.  The '-a' flag
+    selects all unresolved files.
+
+      'hg resolve -m [FILE]: mark a file as having been resolved (e.g.
+    after having manually fixed-up the file(s)).  The default is to
+    mark all unresolved files.
+
+      'hg resolve -u [FILE]...': mark a file as unresolved. The
+    default is to mark all resolved files.
+
+      'hg resolve -l': list files which had or still have conflicts.
+    In the printed list, U=unresolved and R=resolved.
+
+
+    Note that Mercurial will not let you commit files with unresolved
+    merge conflicts.  You must use ``hg resolve -m ...`` before you
+    can commit after a conflicting merge.

     Returns 0 on success, 1 if any files fail a resolve attempt.
     """
@@ -4337,7 +4342,7 @@
          [('a', 'all', None, _('select all unresolved files')),
           ('l', 'list', None, _('list state of files needing merge')),
           ('m', 'mark', None, _('mark files as resolved')),
-          ('u', 'unmark', None, _('unmark files as resolved')),
+          ('u', 'unmark', None, _('mark files as unresolved')),
           ('n', 'no-status', None, _('hide status prefix'))]
           + walkopts,
           _('[OPTION]... [FILE]...')),