filemerge: create detail of internal merge tools from documentation string

this patch introduces 'internaltoolsmarker' which creates detail of
each internal merge tools from documentation string for 'hg help merge-tools'.

Makefile

@@ -91,8 +91,10 b' update-pot: i18n/hg.pot'
 
 i18n/hg.pot: $(PYFILES) $(DOCFILES)
 	$(PYTHON) i18n/hggettext mercurial/commands.py \
-	  hgext/*.py hgext/*/__init__.py mercurial/fileset.py mercurial/revset.py \
+	  hgext/*.py hgext/*/__init__.py \
+	  mercurial/fileset.py mercurial/revset.py \
 	  mercurial/templatefilters.py mercurial/templatekw.py \
+	  mercurial/filemerge.py \
 	  $(DOCFILES) > i18n/hg.pot
         # All strings marked for translation in Mercurial contain
         # ASCII characters only. But some files contain string

mercurial/filemerge.py

@@ -19,19 +19,19 b' def _toolbool(ui, tool, part, default=Fa'
 def _toollist(ui, tool, part, default=[]):
     return ui.configlist("merge-tools", tool + "." + part, default)
 
-_internal = {}
+internals = {}
 
 def internaltool(name, trymerge, onfailure=None):
     '''return a decorator for populating internal merge tool table'''
     def decorator(func):
-        _internal[name] = func
+        internals[name] = func
         func.trymerge = trymerge
         func.onfailure = onfailure
         return func
     return decorator
 
 def _findtool(ui, tool):
-    if tool in _internal:
+    if tool in internals:
         return tool
     for kn in ("regkey", "regkeyalt"):
         k = _toolstr(ui, tool, kn)
@@ -133,6 +133,9 b' def _matcheol(file, origfile):'
 
 @internaltool('internal:prompt', False)
 def _iprompt(repo, mynode, orig, fcd, fco, fca, toolconf):
+    """``internal:prompt``
+    Asks the user which of the local or the other version to keep as
+    the merged version."""
     ui = repo.ui
     fd = fcd.path()
 
@@ -145,15 +148,23 b' def _iprompt(repo, mynode, orig, fcd, fc'
 
 @internaltool('internal:local', False)
 def _ilocal(repo, mynode, orig, fcd, fco, fca, toolconf):
+    """``internal:local``
+    Uses the local version of files as the merged version."""
     return 0
 
 @internaltool('internal:other', False)
 def _iother(repo, mynode, orig, fcd, fco, fca, toolconf):
+    """``internal:other``
+    Uses the other version of files as the merged version."""
     repo.wwrite(fcd.path(), fco.data(), fco.flags())
     return 0
 
 @internaltool('internal:fail', False)
 def _ifail(repo, mynode, orig, fcd, fco, fca, toolconf):
+    """``internal:fail``
+    Rather than attempting to merge files that were modified on both
+    branches, it marks them as unresolved. The resolve command must be
+    used to resolve these conflicts."""
     return 1
 
 def _premerge(repo, toolconf, files):
@@ -187,6 +198,10 b' def _premerge(repo, toolconf, files):'
               _("merging %s incomplete! "
                 "(edit conflicts, then use 'hg resolve --mark')\n"))
 def _imerge(repo, mynode, orig, fcd, fco, fca, toolconf, files):
+    """``internal:merge``
+    Uses the internal non-interactive simple merge algorithm for merging
+    files. It will fail if there are any conflicts and leave markers in
+    the partially merged file."""
     r = _premerge(repo, toolconf, files)
     if r:
         a, b, c, back = files
@@ -199,6 +214,13 b' def _imerge(repo, mynode, orig, fcd, fco'
 
 @internaltool('internal:dump', True)
 def _idump(repo, mynode, orig, fcd, fco, fca, toolconf, files):
+    """``internal:dump``
+    Creates three versions of the files to merge, containing the
+    contents of local, other and base. These files can then be used to
+    perform a merge manually. If the file to be merged is named
+    ``a.txt``, these files will accordingly be named ``a.txt.local``,
+    ``a.txt.other`` and ``a.txt.base`` and they will be placed in the
+    same directory as ``a.txt``."""
     r = _premerge(repo, toolconf, files)
     if r:
         a, b, c, back = files
@@ -267,8 +289,8 b' def filemerge(repo, mynode, orig, fcd, f'
     ui.debug("picked tool '%s' for %s (binary %s symlink %s)\n" %
                (tool, fd, binary, symlink))
 
-    if tool in _internal:
-        func = _internal[tool]
+    if tool in internals:
+        func = internals[tool]
         trymerge = func.trymerge
         onfailure = func.onfailure
     else:
@@ -340,3 +362,6 b' def filemerge(repo, mynode, orig, fcd, f'
     os.unlink(b)
     os.unlink(c)
     return r
+
+# tell hggettext to extract docstrings from these functions:
+i18nfunctions = internals.values()

mercurial/help.py

@@ -7,7 +7,7 b''
 
 from i18n import gettext, _
 import sys, os
-import extensions, revset, fileset, templatekw, templatefilters
+import extensions, revset, fileset, templatekw, templatefilters, filemerge
 import util
 
 def listexts(header, exts, indent=1):
@@ -105,6 +105,7 b' def addtopicsymbols(topic, marker, symbo'
     addtopichook(topic, add)
 
 addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
+addtopicsymbols('merge-tools', '.. internaltoolsmarker', filemerge.internals)
 addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols)
 addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
 addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)

mercurial/help/merge-tools.txt

@@ -34,33 +34,7 b' GUI is available if the tool requires a '
 There are some internal merge tools which can be used. The internal
 merge tools are:
 
-``internal:merge``
-   Uses the internal non-interactive simple merge algorithm for merging
-   files. It will fail if there are any conflicts and leave markers in
-   the partially merged file.
-
-``internal:fail``
-   Rather than attempting to merge files that were modified on both
-   branches, it marks them as unresolved. The resolve command must be
-   used to resolve these conflicts.
-
-``internal:local``
-   Uses the local version of files as the merged version.
-
-``internal:other``
-   Uses the other version of files as the merged version.
-
-``internal:prompt``
-   Asks the user which of the local or the other version to keep as
-   the merged version.
-
-``internal:dump``
-   Creates three versions of the files to merge, containing the
-   contents of local, other and base. These files can then be used to
-   perform a merge manually. If the file to be merged is named
-   ``a.txt``, these files will accordingly be named ``a.txt.local``,
-   ``a.txt.other`` and ``a.txt.base`` and they will be placed in the
-   same directory as ``a.txt``.
+.. internaltoolsmarker
 
 Internal tools are always available and do not require a GUI but will by default
 not handle symlinks or binary files.