help.merge-tools: do not double document merge tools

Merge tools were being double documented in help system output due
to functions being defined under multiple names in the merge tools
dictionary.

Establish a new dictionary for just the tools to document and
use it from the help system so we don't get double output.

Double documentation likely plagues other auto-documented items
as well. It might be a good idea to eventually compare function
instances to filter out duplicate entries from dictionaries
passed to ``makeitemsdoc``. However, without an easy way to break
ties, this may result in some functions being advertised over
their modern equivalents. This would be a noble patch series.
But it isn't one this author is willing to tackle at this time.

mercurial/filemerge.py

@@ -1,473 +1,476 b''
 # filemerge.py - file-level merge handling for Mercurial
 #
 # Copyright 2006, 2007, 2008 Matt Mackall <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 from node import short
 from i18n import _
 import util, simplemerge, match, error, templater, templatekw
 import os, tempfile, re, filecmp
 import tagmerge
 
 def _toolstr(ui, tool, part, default=""):
     return ui.config("merge-tools", tool + "." + part, default)
 
 def _toolbool(ui, tool, part, default=False):
     return ui.configbool("merge-tools", tool + "." + part, default)
 
 def _toollist(ui, tool, part, default=[]):
     return ui.configlist("merge-tools", tool + "." + part, default)
 
 internals = {}
+# Merge tools to document.
+internalsdoc = {}
 
 def internaltool(name, trymerge, onfailure=None):
     '''return a decorator for populating internal merge tool table'''
     def decorator(func):
         fullname = ':' + name
         func.__doc__ = "``%s``\n" % fullname + func.__doc__.strip()
         internals[fullname] = func
         internals['internal:' + name] = func
+        internalsdoc[fullname] = func
         func.trymerge = trymerge
         func.onfailure = onfailure
         return func
     return decorator
 
 def _findtool(ui, tool):
     if tool in internals:
         return tool
     return findexternaltool(ui, tool)
 
 def findexternaltool(ui, tool):
     for kn in ("regkey", "regkeyalt"):
         k = _toolstr(ui, tool, kn)
         if not k:
             continue
         p = util.lookupreg(k, _toolstr(ui, tool, "regname"))
         if p:
             p = util.findexe(p + _toolstr(ui, tool, "regappend"))
             if p:
                 return p
     exe = _toolstr(ui, tool, "executable", tool)
     return util.findexe(util.expandpath(exe))
 
 def _picktool(repo, ui, path, binary, symlink):
     def check(tool, pat, symlink, binary):
         tmsg = tool
         if pat:
             tmsg += " specified for " + pat
         if not _findtool(ui, tool):
             if pat: # explicitly requested tool deserves a warning
                 ui.warn(_("couldn't find merge tool %s\n") % tmsg)
             else: # configured but non-existing tools are more silent
                 ui.note(_("couldn't find merge tool %s\n") % tmsg)
         elif symlink and not _toolbool(ui, tool, "symlink"):
             ui.warn(_("tool %s can't handle symlinks\n") % tmsg)
         elif binary and not _toolbool(ui, tool, "binary"):
             ui.warn(_("tool %s can't handle binary\n") % tmsg)
         elif not util.gui() and _toolbool(ui, tool, "gui"):
             ui.warn(_("tool %s requires a GUI\n") % tmsg)
         else:
             return True
         return False
 
     # forcemerge comes from command line arguments, highest priority
     force = ui.config('ui', 'forcemerge')
     if force:
         toolpath = _findtool(ui, force)
         if toolpath:
             return (force, util.shellquote(toolpath))
         else:
             # mimic HGMERGE if given tool not found
             return (force, force)
 
     # HGMERGE takes next precedence
     hgmerge = os.environ.get("HGMERGE")
     if hgmerge:
         return (hgmerge, hgmerge)
 
     # then patterns
     for pat, tool in ui.configitems("merge-patterns"):
         mf = match.match(repo.root, '', [pat])
         if mf(path) and check(tool, pat, symlink, False):
             toolpath = _findtool(ui, tool)
             return (tool, util.shellquote(toolpath))
 
     # then merge tools
     tools = {}
     for k, v in ui.configitems("merge-tools"):
         t = k.split('.')[0]
         if t not in tools:
             tools[t] = int(_toolstr(ui, t, "priority", "0"))
     names = tools.keys()
     tools = sorted([(-p, t) for t, p in tools.items()])
     uimerge = ui.config("ui", "merge")
     if uimerge:
         if uimerge not in names:
             return (uimerge, uimerge)
         tools.insert(0, (None, uimerge)) # highest priority
     tools.append((None, "hgmerge")) # the old default, if found
     for p, t in tools:
         if check(t, None, symlink, binary):
             toolpath = _findtool(ui, t)
             return (t, util.shellquote(toolpath))
 
     # internal merge or prompt as last resort
     if symlink or binary:
         return ":prompt", None
     return ":merge", None
 
 def _eoltype(data):
     "Guess the EOL type of a file"
     if '\0' in data: # binary
         return None
     if '\r\n' in data: # Windows
         return '\r\n'
     if '\r' in data: # Old Mac
         return '\r'
     if '\n' in data: # UNIX
         return '\n'
     return None # unknown
 
 def _matcheol(file, origfile):
     "Convert EOL markers in a file to match origfile"
     tostyle = _eoltype(util.readfile(origfile))
     if tostyle:
         data = util.readfile(file)
         style = _eoltype(data)
         if style:
             newdata = data.replace(style, tostyle)
             if newdata != data:
                 util.writefile(file, newdata)
 
 @internaltool('prompt', False)
 def _iprompt(repo, mynode, orig, fcd, fco, fca, toolconf):
     """Asks the user which of the local or the other version to keep as
     the merged version."""
     ui = repo.ui
     fd = fcd.path()
 
     if ui.promptchoice(_(" no tool found to merge %s\n"
                          "keep (l)ocal or take (o)ther?"
                          "$$ &Local $$ &Other") % fd, 0):
         return _iother(repo, mynode, orig, fcd, fco, fca, toolconf)
     else:
         return _ilocal(repo, mynode, orig, fcd, fco, fca, toolconf)
 
 @internaltool('local', False)
 def _ilocal(repo, mynode, orig, fcd, fco, fca, toolconf):
     """Uses the local version of files as the merged version."""
     return 0
 
 @internaltool('other', False)
 def _iother(repo, mynode, orig, fcd, fco, fca, toolconf):
     """Uses the other version of files as the merged version."""
     repo.wwrite(fcd.path(), fco.data(), fco.flags())
     return 0
 
 @internaltool('fail', False)
 def _ifail(repo, mynode, orig, fcd, fco, fca, toolconf):
     """
     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, labels=None):
     tool, toolpath, binary, symlink = toolconf
     if symlink:
         return 1
     a, b, c, back = files
 
     ui = repo.ui
 
     validkeep = ['keep', 'keep-merge3']
 
     # do we attempt to simplemerge first?
     try:
         premerge = _toolbool(ui, tool, "premerge", not binary)
     except error.ConfigError:
         premerge = _toolstr(ui, tool, "premerge").lower()
         if premerge not in validkeep:
             _valid = ', '.join(["'" + v + "'" for v in validkeep])
             raise error.ConfigError(_("%s.premerge not valid "
                                       "('%s' is neither boolean nor %s)") %
                                     (tool, premerge, _valid))
 
     if premerge:
         if premerge == 'keep-merge3':
             if not labels:
                 labels = _defaultconflictlabels
             if len(labels) < 3:
                 labels.append('base')
         r = simplemerge.simplemerge(ui, a, b, c, quiet=True, label=labels)
         if not r:
             ui.debug(" premerge successful\n")
             return 0
         if premerge not in validkeep:
             util.copyfile(back, a) # restore from backup and try again
     return 1 # continue merging
 
 @internaltool('merge', True,
               _("merging %s incomplete! "
                 "(edit conflicts, then use 'hg resolve --mark')\n"))
 def _imerge(repo, mynode, orig, fcd, fco, fca, toolconf, files, labels=None):
     """
     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. Markers will have two sections, one for each side
     of merge."""
     tool, toolpath, binary, symlink = toolconf
     if symlink:
         repo.ui.warn(_('warning: internal :merge cannot merge symlinks '
                        'for %s\n') % fcd.path())
         return False, 1
     r = _premerge(repo, toolconf, files, labels=labels)
     if r:
         a, b, c, back = files
 
         ui = repo.ui
 
         r = simplemerge.simplemerge(ui, a, b, c, label=labels)
         return True, r
     return False, 0
 
 @internaltool('merge3', True,
               _("merging %s incomplete! "
                 "(edit conflicts, then use 'hg resolve --mark')\n"))
 def _imerge3(repo, mynode, orig, fcd, fco, fca, toolconf, files, labels=None):
     """
     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. Marker will have three sections, one from each
     side of the merge and one for the base content."""
     if not labels:
         labels = _defaultconflictlabels
     if len(labels) < 3:
         labels.append('base')
     return _imerge(repo, mynode, orig, fcd, fco, fca, toolconf, files, labels)
 
 @internaltool('tagmerge', True,
               _("automatic tag merging of %s failed! "
                 "(use 'hg resolve --tool :merge' or another merge "
                 "tool of your choice)\n"))
 def _itagmerge(repo, mynode, orig, fcd, fco, fca, toolconf, files, labels=None):
     """
     Uses the internal tag merge algorithm (experimental).
     """
     return tagmerge.merge(repo, fcd, fco, fca)
 
 @internaltool('dump', True)
 def _idump(repo, mynode, orig, fcd, fco, fca, toolconf, files, labels=None):
     """
     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, labels=labels)
     if r:
         a, b, c, back = files
 
         fd = fcd.path()
 
         util.copyfile(a, a + ".local")
         repo.wwrite(fd + ".other", fco.data(), fco.flags())
         repo.wwrite(fd + ".base", fca.data(), fca.flags())
     return False, r
 
 def _xmerge(repo, mynode, orig, fcd, fco, fca, toolconf, files, labels=None):
     r = _premerge(repo, toolconf, files, labels=labels)
     if r:
         tool, toolpath, binary, symlink = toolconf
         a, b, c, back = files
         out = ""
         env = {'HG_FILE': fcd.path(),
                'HG_MY_NODE': short(mynode),
                'HG_OTHER_NODE': str(fco.changectx()),
                'HG_BASE_NODE': str(fca.changectx()),
                'HG_MY_ISLINK': 'l' in fcd.flags(),
                'HG_OTHER_ISLINK': 'l' in fco.flags(),
                'HG_BASE_ISLINK': 'l' in fca.flags(),
                }
 
         ui = repo.ui
 
         args = _toolstr(ui, tool, "args", '$local $base $other')
         if "$output" in args:
             out, a = a, back # read input from backup, write to original
         replace = {'local': a, 'base': b, 'other': c, 'output': out}
         args = util.interpolate(r'\$', replace, args,
                                 lambda s: util.shellquote(util.localpath(s)))
         r = ui.system(toolpath + ' ' + args, cwd=repo.root, environ=env)
         return True, r
     return False, 0
 
 def _formatconflictmarker(repo, ctx, template, label, pad):
     """Applies the given template to the ctx, prefixed by the label.
 
     Pad is the minimum width of the label prefix, so that multiple markers
     can have aligned templated parts.
     """
     if ctx.node() is None:
         ctx = ctx.p1()
 
     props = templatekw.keywords.copy()
     props['templ'] = template
     props['ctx'] = ctx
     props['repo'] = repo
     templateresult = template('conflictmarker', **props)
 
     label = ('%s:' % label).ljust(pad + 1)
     mark = '%s %s' % (label, templater.stringify(templateresult))
 
     if mark:
         mark = mark.splitlines()[0] # split for safety
 
     # 8 for the prefix of conflict marker lines (e.g. '<<<<<<< ')
     return util.ellipsis(mark, 80 - 8)
 
 _defaultconflictmarker = ('{node|short} ' +
     '{ifeq(tags, "tip", "", "{tags} ")}' +
     '{if(bookmarks, "{bookmarks} ")}' +
     '{ifeq(branch, "default", "", "{branch} ")}' +
     '- {author|user}: {desc|firstline}')
 
 _defaultconflictlabels = ['local', 'other']
 
 def _formatlabels(repo, fcd, fco, fca, labels):
     """Formats the given labels using the conflict marker template.
 
     Returns a list of formatted labels.
     """
     cd = fcd.changectx()
     co = fco.changectx()
     ca = fca.changectx()
 
     ui = repo.ui
     template = ui.config('ui', 'mergemarkertemplate', _defaultconflictmarker)
     template = templater.parsestring(template, quoted=False)
     tmpl = templater.templater(None, cache={'conflictmarker': template})
 
     pad = max(len(l) for l in labels)
 
     newlabels = [_formatconflictmarker(repo, cd, tmpl, labels[0], pad),
                  _formatconflictmarker(repo, co, tmpl, labels[1], pad)]
     if len(labels) > 2:
         newlabels.append(_formatconflictmarker(repo, ca, tmpl, labels[2], pad))
     return newlabels
 
 def filemerge(repo, mynode, orig, fcd, fco, fca, labels=None):
     """perform a 3-way merge in the working directory
 
     mynode = parent node before merge
     orig = original local filename before merge
     fco = other file context
     fca = ancestor file context
     fcd = local file context for current/destination file
     """
 
     def temp(prefix, ctx):
         pre = "%s~%s." % (os.path.basename(ctx.path()), prefix)
         (fd, name) = tempfile.mkstemp(prefix=pre)
         data = repo.wwritedata(ctx.path(), ctx.data())
         f = os.fdopen(fd, "wb")
         f.write(data)
         f.close()
         return name
 
     if not fco.cmp(fcd): # files identical?
         return None
 
     ui = repo.ui
     fd = fcd.path()
     binary = fcd.isbinary() or fco.isbinary() or fca.isbinary()
     symlink = 'l' in fcd.flags() + fco.flags()
     tool, toolpath = _picktool(repo, ui, fd, binary, symlink)
     ui.debug("picked tool '%s' for %s (binary %s symlink %s)\n" %
                (tool, fd, binary, symlink))
 
     if tool in internals:
         func = internals[tool]
         trymerge = func.trymerge
         onfailure = func.onfailure
     else:
         func = _xmerge
         trymerge = True
         onfailure = _("merging %s failed!\n")
 
     toolconf = tool, toolpath, binary, symlink
 
     if not trymerge:
         return func(repo, mynode, orig, fcd, fco, fca, toolconf)
 
     a = repo.wjoin(fd)
     b = temp("base", fca)
     c = temp("other", fco)
     back = a + ".orig"
     util.copyfile(a, back)
 
     if orig != fco.path():
         ui.status(_("merging %s and %s to %s\n") % (orig, fco.path(), fd))
     else:
         ui.status(_("merging %s\n") % fd)
 
     ui.debug("my %s other %s ancestor %s\n" % (fcd, fco, fca))
 
     markerstyle = ui.config('ui', 'mergemarkers', 'basic')
     if not labels:
         labels = _defaultconflictlabels
     if markerstyle != 'basic':
         labels = _formatlabels(repo, fcd, fco, fca, labels)
 
     needcheck, r = func(repo, mynode, orig, fcd, fco, fca, toolconf,
                         (a, b, c, back), labels=labels)
     if not needcheck:
         if r:
             if onfailure:
                 ui.warn(onfailure % fd)
         else:
             util.unlink(back)
 
         util.unlink(b)
         util.unlink(c)
         return r
 
     if not r and (_toolbool(ui, tool, "checkconflicts") or
                   'conflicts' in _toollist(ui, tool, "check")):
         if re.search("^(<<<<<<< .*|=======|>>>>>>> .*)$", fcd.data(),
                      re.MULTILINE):
             r = 1
 
     checked = False
     if 'prompt' in _toollist(ui, tool, "check"):
         checked = True
         if ui.promptchoice(_("was merge of '%s' successful (yn)?"
                              "$$ &Yes $$ &No") % fd, 1):
             r = 1
 
     if not r and not checked and (_toolbool(ui, tool, "checkchanged") or
                                   'changed' in _toollist(ui, tool, "check")):
         if filecmp.cmp(a, back):
             if ui.promptchoice(_(" output file %s appears unchanged\n"
                                  "was merge successful (yn)?"
                                  "$$ &Yes $$ &No") % fd, 1):
                 r = 1
 
     if _toolbool(ui, tool, "fixeol"):
         _matcheol(a, back)
 
     if r:
         if onfailure:
             ui.warn(onfailure % fd)
     else:
         util.unlink(back)
 
     util.unlink(b)
     util.unlink(c)
     return r
 
 # tell hggettext to extract docstrings from these functions:
 i18nfunctions = internals.values()

mercurial/help.py

@@ -1,512 +1,513 b''
 # help.py - help data for mercurial
 #
 # Copyright 2006 Matt Mackall <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 from i18n import gettext, _
 import itertools, os, textwrap
 import error
 import extensions, revset, fileset, templatekw, templatefilters, filemerge
 import encoding, util, minirst
 import cmdutil
 import hgweb.webcommands as webcommands
 
 def listexts(header, exts, indent=1, showdeprecated=False):
     '''return a text listing of the given extensions'''
     rst = []
     if exts:
         rst.append('\n%s\n\n' % header)
         for name, desc in sorted(exts.iteritems()):
             if '(DEPRECATED)' in desc and not showdeprecated:
                 continue
             rst.append('%s:%s: %s\n' % (' ' * indent, name, desc))
     return rst
 
 def extshelp():
     rst = loaddoc('extensions')().splitlines(True)
     rst.extend(listexts(
         _('enabled extensions:'), extensions.enabled(), showdeprecated=True))
     rst.extend(listexts(_('disabled extensions:'), extensions.disabled()))
     doc = ''.join(rst)
     return doc
 
 def optrst(header, options, verbose):
     data = []
     multioccur = False
     for option in options:
         if len(option) == 5:
             shortopt, longopt, default, desc, optlabel = option
         else:
             shortopt, longopt, default, desc = option
             optlabel = _("VALUE") # default label
 
         if not verbose and ("DEPRECATED" in desc or _("DEPRECATED") in desc):
             continue
 
         so = ''
         if shortopt:
             so = '-' + shortopt
         lo = '--' + longopt
         if default:
             desc += _(" (default: %s)") % default
 
         if isinstance(default, list):
             lo += " %s [+]" % optlabel
             multioccur = True
         elif (default is not None) and not isinstance(default, bool):
             lo += " %s" % optlabel
 
         data.append((so, lo, desc))
 
     if multioccur:
         header += (_(" ([+] can be repeated)"))
 
     rst = ['\n%s:\n\n' % header]
     rst.extend(minirst.maketable(data, 1))
 
     return ''.join(rst)
 
 def indicateomitted(rst, omitted, notomitted=None):
     rst.append('\n\n.. container:: omitted\n\n    %s\n\n' % omitted)
     if notomitted:
         rst.append('\n\n.. container:: notomitted\n\n    %s\n\n' % notomitted)
 
 def topicmatch(kw):
     """Return help topics matching kw.
 
     Returns {'section': [(name, summary), ...], ...} where section is
     one of topics, commands, extensions, or extensioncommands.
     """
     kw = encoding.lower(kw)
     def lowercontains(container):
         return kw in encoding.lower(container)  # translated in helptable
     results = {'topics': [],
                'commands': [],
                'extensions': [],
                'extensioncommands': [],
                }
     for names, header, doc in helptable:
         # Old extensions may use a str as doc.
         if (sum(map(lowercontains, names))
             or lowercontains(header)
             or (callable(doc) and lowercontains(doc()))):
             results['topics'].append((names[0], header))
     import commands # avoid cycle
     for cmd, entry in commands.table.iteritems():
         if len(entry) == 3:
             summary = entry[2]
         else:
             summary = ''
         # translate docs *before* searching there
         docs = _(getattr(entry[0], '__doc__', None)) or ''
         if kw in cmd or lowercontains(summary) or lowercontains(docs):
             doclines = docs.splitlines()
             if doclines:
                 summary = doclines[0]
             cmdname = cmd.split('|')[0].lstrip('^')
             results['commands'].append((cmdname, summary))
     for name, docs in itertools.chain(
         extensions.enabled(False).iteritems(),
         extensions.disabled().iteritems()):
         # extensions.load ignores the UI argument
         mod = extensions.load(None, name, '')
         name = name.split('.')[-1]
         if lowercontains(name) or lowercontains(docs):
             # extension docs are already translated
             results['extensions'].append((name, docs.splitlines()[0]))
         for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems():
             if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])):
                 cmdname = cmd.split('|')[0].lstrip('^')
                 if entry[0].__doc__:
                     cmddoc = gettext(entry[0].__doc__).splitlines()[0]
                 else:
                     cmddoc = _('(no help text available)')
                 results['extensioncommands'].append((cmdname, cmddoc))
     return results
 
 def loaddoc(topic):
     """Return a delayed loader for help/topic.txt."""
 
     def loader():
         docdir = os.path.join(util.datapath, 'help')
         path = os.path.join(docdir, topic + ".txt")
         doc = gettext(util.readfile(path))
         for rewriter in helphooks.get(topic, []):
             doc = rewriter(topic, doc)
         return doc
 
     return loader
 
 helptable = sorted([
     (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
     (["dates"], _("Date Formats"), loaddoc('dates')),
     (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
     (['environment', 'env'], _('Environment Variables'),
      loaddoc('environment')),
     (['revisions', 'revs'], _('Specifying Single Revisions'),
      loaddoc('revisions')),
     (['multirevs', 'mrevs'], _('Specifying Multiple Revisions'),
      loaddoc('multirevs')),
     (['revsets', 'revset'], _("Specifying Revision Sets"), loaddoc('revsets')),
     (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')),
     (['diffs'], _('Diff Formats'), loaddoc('diffs')),
     (['merge-tools', 'mergetools'], _('Merge Tools'), loaddoc('merge-tools')),
     (['templating', 'templates', 'template', 'style'], _('Template Usage'),
      loaddoc('templates')),
     (['urls'], _('URL Paths'), loaddoc('urls')),
     (["extensions"], _("Using Additional Features"), extshelp),
     (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')),
     (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
     (["glossary"], _("Glossary"), loaddoc('glossary')),
     (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
      loaddoc('hgignore')),
     (["phases"], _("Working with Phases"), loaddoc('phases')),
 ])
 
 # Map topics to lists of callable taking the current topic help and
 # returning the updated version
 helphooks = {}
 
 def addtopichook(topic, rewriter):
     helphooks.setdefault(topic, []).append(rewriter)
 
 def makeitemsdoc(topic, doc, marker, items, dedent=False):
     """Extract docstring from the items key to function mapping, build a
     .single documentation block and use it to overwrite the marker in doc
     """
     entries = []
     for name in sorted(items):
         text = (items[name].__doc__ or '').rstrip()
         if not text:
             continue
         text = gettext(text)
         if dedent:
             text = textwrap.dedent(text)
         lines = text.splitlines()
         doclines = [(lines[0])]
         for l in lines[1:]:
             # Stop once we find some Python doctest
             if l.strip().startswith('>>>'):
                 break
             if dedent:
                 doclines.append(l.rstrip())
             else:
                 doclines.append('  ' + l.strip())
         entries.append('\n'.join(doclines))
     entries = '\n\n'.join(entries)
     return doc.replace(marker, entries)
 
 def addtopicsymbols(topic, marker, symbols, dedent=False):
     def add(topic, doc):
         return makeitemsdoc(topic, doc, marker, symbols, dedent=dedent)
     addtopichook(topic, add)
 
 addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
-addtopicsymbols('merge-tools', '.. internaltoolsmarker', filemerge.internals)
+addtopicsymbols('merge-tools', '.. internaltoolsmarker',
+                filemerge.internalsdoc)
 addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols)
 addtopicsymbols('templates', '.. keywordsmarker', templatekw.dockeywords)
 addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
 addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands,
                 dedent=True)
 
 def help_(ui, name, unknowncmd=False, full=True, **opts):
     '''
     Generate the help for 'name' as unformatted restructured text. If
     'name' is None, describe the commands available.
     '''
 
     import commands # avoid cycle
 
     def helpcmd(name):
         try:
             aliases, entry = cmdutil.findcmd(name, commands.table,
                                              strict=unknowncmd)
         except error.AmbiguousCommand, inst:
             # py3k fix: except vars can't be used outside the scope of the
             # except block, nor can be used inside a lambda. python issue4617
             prefix = inst.args[0]
             select = lambda c: c.lstrip('^').startswith(prefix)
             rst = helplist(select)
             return rst
 
         rst = []
 
         # check if it's an invalid alias and display its error if it is
         if getattr(entry[0], 'badalias', None):
             rst.append(entry[0].badalias + '\n')
             if entry[0].unknowncmd:
                 try:
                     rst.extend(helpextcmd(entry[0].cmdname))
                 except error.UnknownCommand:
                     pass
             return rst
 
         # synopsis
         if len(entry) > 2:
             if entry[2].startswith('hg'):
                 rst.append("%s\n" % entry[2])
             else:
                 rst.append('hg %s %s\n' % (aliases[0], entry[2]))
         else:
             rst.append('hg %s\n' % aliases[0])
         # aliases
         if full and not ui.quiet and len(aliases) > 1:
             rst.append(_("\naliases: %s\n") % ', '.join(aliases[1:]))
         rst.append('\n')
 
         # description
         doc = gettext(entry[0].__doc__)
         if not doc:
             doc = _("(no help text available)")
         if util.safehasattr(entry[0], 'definition'):  # aliased command
             if entry[0].definition.startswith('!'):  # shell alias
                 doc = _('shell alias for::\n\n    %s') % entry[0].definition[1:]
             else:
                 doc = _('alias for: hg %s\n\n%s') % (entry[0].definition, doc)
         doc = doc.splitlines(True)
         if ui.quiet or not full:
             rst.append(doc[0])
         else:
             rst.extend(doc)
         rst.append('\n')
 
         # check if this command shadows a non-trivial (multi-line)
         # extension help text
         try:
             mod = extensions.find(name)
             doc = gettext(mod.__doc__) or ''
             if '\n' in doc.strip():
                 msg = _('(use "hg help -e %s" to show help for '
                         'the %s extension)') % (name, name)
                 rst.append('\n%s\n' % msg)
         except KeyError:
             pass
 
         # options
         if not ui.quiet and entry[1]:
             rst.append(optrst(_("options"), entry[1], ui.verbose))
 
         if ui.verbose:
             rst.append(optrst(_("global options"),
                               commands.globalopts, ui.verbose))
 
         if not ui.verbose:
             if not full:
                 rst.append(_('\n(use "hg %s -h" to show more help)\n')
                            % name)
             elif not ui.quiet:
                 rst.append(_('\n(some details hidden, use --verbose '
                                'to show complete help)'))
 
         return rst
 
 
     def helplist(select=None):
         # list of commands
         if name == "shortlist":
             header = _('basic commands:\n\n')
         elif name == "debug":
             header = _('debug commands (internal and unsupported):\n\n')
         else:
             header = _('list of commands:\n\n')
 
         h = {}
         cmds = {}
         for c, e in commands.table.iteritems():
             f = c.split("|", 1)[0]
             if select and not select(f):
                 continue
             if (not select and name != 'shortlist' and
                 e[0].__module__ != commands.__name__):
                 continue
             if name == "shortlist" and not f.startswith("^"):
                 continue
             f = f.lstrip("^")
             if not ui.debugflag and f.startswith("debug") and name != "debug":
                 continue
             doc = e[0].__doc__
             if doc and 'DEPRECATED' in doc and not ui.verbose:
                 continue
             doc = gettext(doc)
             if not doc:
                 doc = _("(no help text available)")
             h[f] = doc.splitlines()[0].rstrip()
             cmds[f] = c.lstrip("^")
 
         rst = []
         if not h:
             if not ui.quiet:
                 rst.append(_('no commands defined\n'))
             return rst
 
         if not ui.quiet:
             rst.append(header)
         fns = sorted(h)
         for f in fns:
             if ui.verbose:
                 commacmds = cmds[f].replace("|",", ")
                 rst.append(" :%s: %s\n" % (commacmds, h[f]))
             else:
                 rst.append(' :%s: %s\n' % (f, h[f]))
 
         if not name:
             exts = listexts(_('enabled extensions:'), extensions.enabled())
             if exts:
                 rst.append('\n')
                 rst.extend(exts)
 
             rst.append(_("\nadditional help topics:\n\n"))
             topics = []
             for names, header, doc in helptable:
                 topics.append((names[0], header))
             for t, desc in topics:
                 rst.append(" :%s: %s\n" % (t, desc))
 
         if ui.quiet:
             pass
         elif ui.verbose:
             rst.append('\n%s\n' % optrst(_("global options"),
                                          commands.globalopts, ui.verbose))
             if name == 'shortlist':
                 rst.append(_('\n(use "hg help" for the full list '
                              'of commands)\n'))
         else:
             if name == 'shortlist':
                 rst.append(_('\n(use "hg help" for the full list of commands '
                              'or "hg -v" for details)\n'))
             elif name and not full:
                 rst.append(_('\n(use "hg help %s" to show the full help '
                              'text)\n') % name)
             elif name and cmds and name in cmds.keys():
                 rst.append(_('\n(use "hg help -v -e %s" to show built-in '
                              'aliases and global options)\n') % name)
             else:
                 rst.append(_('\n(use "hg help -v%s" to show built-in aliases '
                              'and global options)\n')
                            % (name and " " + name or ""))
         return rst
 
     def helptopic(name):
         for names, header, doc in helptable:
             if name in names:
                 break
         else:
             raise error.UnknownCommand(name)
 
         rst = [minirst.section(header)]
 
         # description
         if not doc:
             rst.append("    %s\n" % _("(no help text available)"))
         if callable(doc):
             rst += ["    %s\n" % l for l in doc().splitlines()]
 
         if not ui.verbose:
             omitted = _('(some details hidden, use --verbose'
                          ' to show complete help)')
             indicateomitted(rst, omitted)
 
         try:
             cmdutil.findcmd(name, commands.table)
             rst.append(_('\nuse "hg help -c %s" to see help for '
                        'the %s command\n') % (name, name))
         except error.UnknownCommand:
             pass
         return rst
 
     def helpext(name):
         try:
             mod = extensions.find(name)
             doc = gettext(mod.__doc__) or _('no help text available')
         except KeyError:
             mod = None
             doc = extensions.disabledext(name)
             if not doc:
                 raise error.UnknownCommand(name)
 
         if '\n' not in doc:
             head, tail = doc, ""
         else:
             head, tail = doc.split('\n', 1)
         rst = [_('%s extension - %s\n\n') % (name.split('.')[-1], head)]
         if tail:
             rst.extend(tail.splitlines(True))
             rst.append('\n')
 
         if not ui.verbose:
             omitted = _('(some details hidden, use --verbose'
                          ' to show complete help)')
             indicateomitted(rst, omitted)
 
         if mod:
             try:
                 ct = mod.cmdtable
             except AttributeError:
                 ct = {}
             modcmds = set([c.split('|', 1)[0] for c in ct])
             rst.extend(helplist(modcmds.__contains__))
         else:
             rst.append(_('(use "hg help extensions" for information on enabling'
                        ' extensions)\n'))
         return rst
 
     def helpextcmd(name):
         cmd, ext, mod = extensions.disabledcmd(ui, name,
                                                ui.configbool('ui', 'strict'))
         doc = gettext(mod.__doc__).splitlines()[0]
 
         rst = listexts(_("'%s' is provided by the following "
                               "extension:") % cmd, {ext: doc}, indent=4)
         rst.append('\n')
         rst.append(_('(use "hg help extensions" for information on enabling '
                    'extensions)\n'))
         return rst
 
 
     rst = []
     kw = opts.get('keyword')
     if kw:
         matches = topicmatch(kw)
         for t, title in (('topics', _('Topics')),
                          ('commands', _('Commands')),
                          ('extensions', _('Extensions')),
                          ('extensioncommands', _('Extension Commands'))):
             if matches[t]:
                 rst.append('%s:\n\n' % title)
                 rst.extend(minirst.maketable(sorted(matches[t]), 1))
                 rst.append('\n')
         if not rst:
             msg = _('no matches')
             hint = _('try "hg help" for a list of topics')
             raise util.Abort(msg, hint=hint)
     elif name and name != 'shortlist':
         if unknowncmd:
             queries = (helpextcmd,)
         elif opts.get('extension'):
             queries = (helpext,)
         elif opts.get('command'):
             queries = (helpcmd,)
         else:
             queries = (helptopic, helpcmd, helpext, helpextcmd)
         for f in queries:
             try:
                 rst = f(name)
                 break
             except error.UnknownCommand:
                 pass
         else:
             if unknowncmd:
                 raise error.UnknownCommand(name)
             else:
                 msg = _('no such help topic: %s') % name
                 hint = _('try "hg help --keyword %s"') % name
                 raise util.Abort(msg, hint=hint)
     else:
         # program name
         if not ui.quiet:
             rst = [_("Mercurial Distributed SCM\n"), '\n']
         rst.extend(helplist())
 
     return ''.join(rst)