heads: modernize documentation (issue3992)

The old docs emphasized topological heads rather than branch heads and
incorrectly defined branch heads as not having children rather than
descendants.

mercurial/commands.py

@@ -3320,19 +3320,17 b' def grep(ui, repo, pattern, *pats, **opt'
     ] + templateopts,
     _('[-ct] [-r STARTREV] [REV]...'))
 def heads(ui, repo, *branchrevs, **opts):
-    """show current repository heads or show branch heads
-
-    With no arguments, show all repository branch heads.
-
-    Repository "heads" are changesets with no child changesets. They are
-    where development generally takes place and are the usual targets
-    for update and merge operations. Branch heads are changesets that have
-    no child changeset on the same branch.
-
-    If one or more REVs are given, only branch heads on the branches
-    associated with the specified changesets are shown. This means
-    that you can use :hg:`heads foo` to see the heads on a branch
-    named ``foo``.
+    """show branch heads
+
+    With no arguments, show all open branch heads in the repository.
+    Branch heads are changesets that have no child changesets on the
+    same branch. They are where development generally takes place and
+    are the usual targets for update and merge operations.
+
+    If one or more REVs are given, only open branch heads on the
+    branches associated with the specified changesets are shown. This
+    means that you can use :hg:`heads .` to see the heads on the
+    currently checked-out branch.
 
     If -c/--closed is specified, also show branch heads marked closed
     (see :hg:`commit --close-branch`).
@@ -3341,7 +3339,7 b' def heads(ui, repo, *branchrevs, **opts)'
     STARTREV will be displayed.
 
     If -t/--topo is specified, named branch mechanics will be ignored and only
-    changesets without children will be shown.
+    topological heads (changesets with no children) will be shown.
 
     Returns 0 if matching heads are found, 1 if not.
     """

tests/test-globalopts.t

@@ -303,7 +303,7 b' Testing -h/--help:'
    forget        forget the specified files on the next commit
    graft         copy changes from other branches onto the current branch
    grep          search for a pattern in specified files and revisions
-   heads         show current repository heads or show branch heads
+   heads         show branch heads
    help          show help for a given topic or a help overview
    identify      identify the working copy or specified revision
    import        import an ordered set of patches
@@ -385,7 +385,7 b' Testing -h/--help:'
    forget        forget the specified files on the next commit
    graft         copy changes from other branches onto the current branch
    grep          search for a pattern in specified files and revisions
-   heads         show current repository heads or show branch heads
+   heads         show branch heads
    help          show help for a given topic or a help overview
    identify      identify the working copy or specified revision
    import        import an ordered set of patches

tests/test-help.t

@@ -68,7 +68,7 b' Short help:'
    forget        forget the specified files on the next commit
    graft         copy changes from other branches onto the current branch
    grep          search for a pattern in specified files and revisions
-   heads         show current repository heads or show branch heads
+   heads         show branch heads
    help          show help for a given topic or a help overview
    identify      identify the working copy or specified revision
    import        import an ordered set of patches
@@ -144,7 +144,7 b' Short help:'
    forget        forget the specified files on the next commit
    graft         copy changes from other branches onto the current branch
    grep          search for a pattern in specified files and revisions
-   heads         show current repository heads or show branch heads
+   heads         show branch heads
    help          show help for a given topic or a help overview
    identify      identify the working copy or specified revision
    import        import an ordered set of patches
@@ -629,7 +629,7 b' Test that default list of commands omits'
    forget        forget the specified files on the next commit
    graft         copy changes from other branches onto the current branch
    grep          search for a pattern in specified files and revisions
-   heads         show current repository heads or show branch heads
+   heads         show branch heads
    help          show help for a given topic or a help overview
    identify      identify the working copy or specified revision
    import        import an ordered set of patches
@@ -1276,7 +1276,7 b' Dish up an empty repo; serve it cold.'
   heads
   </a>
   </td><td>
-  show current repository heads or show branch heads
+  show branch heads
   </td></tr>
   <tr><td>
   <a href="/help/help">