diff --git a/mercurial/commands.py b/mercurial/commands.py --- a/mercurial/commands.py +++ b/mercurial/commands.py @@ -7,9 +7,9 @@ from node import hex, bin, nullid, nullrev, short from lock import release -from i18n import _, gettext +from i18n import _ import os, re, difflib, time, tempfile, errno -import hg, scmutil, util, revlog, extensions, copies, error, bookmarks +import hg, scmutil, util, revlog, copies, error, bookmarks import patch, help, encoding, templatekw, discovery import archival, changegroup, cmdutil, hbisect import sshserver, hgweb, hgweb.server, commandserver @@ -3214,7 +3214,7 @@ def heads(ui, repo, *branchrevs, **opts) ('k', 'keyword', '', _('show topics matching keyword')), ], _('[-ec] [TOPIC]')) -def help_(ui, name=None, unknowncmd=False, full=True, **opts): +def help_(ui, name=None, **opts): """show help for a given topic or a help overview With no arguments, print a list of commands with short help messages. @@ -3227,291 +3227,9 @@ def help_(ui, name=None, unknowncmd=Fals textwidth = min(ui.termwidth(), 80) - 2 - def helpcmd(name): - try: - aliases, entry = cmdutil.findcmd(name, 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', False): - if not unknowncmd: - ui.pushbuffer() - entry[0](ui) - rst.append(ui.popbuffer()) - 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('\n%s\n\n' % _("options:")) - rst.append(help.optrst(entry[1], ui.verbose)) - - if ui.verbose: - rst.append('\n%s\n\n' % _("global options:")) - rst.append(help.optrst(globalopts, ui.verbose)) - - if not ui.verbose: - if not full: - rst.append(_('\nuse "hg help %s" to show the full help text\n') - % name) - elif not ui.quiet: - omitted = _('use "hg -v help %s" to show more complete' - ' help and the global options') % name - notomitted = _('use "hg -v help %s" to show' - ' the global options') % name - help.indicateomitted(rst, omitted, notomitted) - - return rst - - - def helplist(select=None): - # list of commands - if name == "shortlist": - header = _('basic commands:\n\n') - else: - header = _('list of commands:\n\n') - - h = {} - cmds = {} - for c, e in table.iteritems(): - f = c.split("|", 1)[0] - if select and not select(f): - continue - if (not select and name != 'shortlist' and - e[0].__module__ != __name__): - continue - if name == "shortlist" and not f.startswith("^"): - continue - f = f.lstrip("^") - if not ui.debugflag and f.startswith("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: - commands = cmds[f].replace("|",", ") - rst.append(" :%s: %s\n" % (commands, h[f])) - else: - rst.append(' :%s: %s\n' % (f, h[f])) - - if not name: - exts = help.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 help.helptable: - topics.append((names[0], header)) - for t, desc in topics: - rst.append(" :%s: %s\n" % (t, desc)) - - optlist = [] - if not ui.quiet: - if ui.verbose: - optlist.append((_("global options:"), globalopts)) - if name == 'shortlist': - optlist.append((_('use "hg help" for the full list ' - 'of commands'), ())) - else: - if name == 'shortlist': - msg = _('use "hg help" for the full list of commands ' - 'or "hg -v" for details') - elif name and not full: - msg = _('use "hg help %s" to show the full help ' - 'text') % name - else: - msg = _('use "hg -v help%s" to show builtin aliases and ' - 'global options') % (name and " " + name or "") - optlist.append((msg, ())) - - if optlist: - for title, options in optlist: - rst.append('\n%s\n' % title) - if options: - rst.append('\n%s\n' % help.optrst(options, ui.verbose)) - return rst - - def helptopic(name): - for names, header, doc in help.helptable: - if name in names: - break - else: - raise error.UnknownCommand(name) - - rst = ["%s\n\n" % header] - # description - if not doc: - rst.append(" %s\n" % _("(no help text available)")) - if util.safehasattr(doc, '__call__'): - rst += [" %s\n" % l for l in doc().splitlines()] - - if not ui.verbose: - omitted = (_('use "hg help -v %s" to show more complete help') % - name) - help.indicateomitted(rst, omitted) - - try: - cmdutil.findcmd(name, 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 = (_('use "hg help -v %s" to show more complete help') % - name) - 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 = help.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 = help.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') - elif name and name != 'shortlist': - i = None - 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) - i = None - break - except error.UnknownCommand, inst: - i = inst - if i: - raise i - else: - # program name - if not ui.quiet: - rst = [_("Mercurial Distributed SCM\n"), '\n'] - rst.extend(helplist()) - keep = ui.verbose and ['verbose'] or [] - text = ''.join(rst) + text = help.help_(ui, name, **opts) + formatted, pruned = minirst.format(text, textwidth, keep=keep) if 'verbose' in pruned: keep.append('omitted') diff --git a/mercurial/help.py b/mercurial/help.py --- a/mercurial/help.py +++ b/mercurial/help.py @@ -6,9 +6,10 @@ # GNU General Public License version 2 or any later version. from i18n import gettext, _ -import itertools, sys, os +import itertools, sys, os, error import extensions, revset, fileset, templatekw, templatefilters, filemerge import encoding, util, minirst +import cmdutil def listexts(header, exts, indent=1): '''return a text listing of the given extensions''' @@ -206,3 +207,297 @@ addtopicsymbols('merge-tools', '.. inter addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols) addtopicsymbols('templates', '.. keywordsmarker', templatekw.dockeywords) addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters) + +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', False): + if not unknowncmd: + ui.pushbuffer() + entry[0](ui) + rst.append(ui.popbuffer()) + 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('\n%s\n\n' % _("options:")) + rst.append(optrst(entry[1], ui.verbose)) + + if ui.verbose: + rst.append('\n%s\n\n' % _("global options:")) + rst.append(optrst(commands.globalopts, ui.verbose)) + + if not ui.verbose: + if not full: + rst.append(_('\nuse "hg help %s" to show the full help text\n') + % name) + elif not ui.quiet: + omitted = _('use "hg -v help %s" to show more complete' + ' help and the global options') % name + notomitted = _('use "hg -v help %s" to show' + ' the global options') % name + indicateomitted(rst, omitted, notomitted) + + return rst + + + def helplist(select=None): + # list of commands + if name == "shortlist": + header = _('basic commands:\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"): + 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)) + + optlist = [] + if not ui.quiet: + if ui.verbose: + optlist.append((_("global options:"), commands.globalopts)) + if name == 'shortlist': + optlist.append((_('use "hg help" for the full list ' + 'of commands'), ())) + else: + if name == 'shortlist': + msg = _('use "hg help" for the full list of commands ' + 'or "hg -v" for details') + elif name and not full: + msg = _('use "hg help %s" to show the full help ' + 'text') % name + else: + msg = _('use "hg -v help%s" to show builtin aliases and ' + 'global options') % (name and " " + name or "") + optlist.append((msg, ())) + + if optlist: + for title, options in optlist: + rst.append('\n%s\n' % title) + if options: + rst.append('\n%s\n' % optrst(options, ui.verbose)) + return rst + + def helptopic(name): + for names, header, doc in helptable: + if name in names: + break + else: + raise error.UnknownCommand(name) + + rst = ["%s\n\n" % header] + # description + if not doc: + rst.append(" %s\n" % _("(no help text available)")) + if util.safehasattr(doc, '__call__'): + rst += [" %s\n" % l for l in doc().splitlines()] + + if not ui.verbose: + omitted = (_('use "hg help -v %s" to show more complete help') % + name) + 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 = (_('use "hg help -v %s" to show more complete help') % + name) + 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') + elif name and name != 'shortlist': + i = None + 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) + i = None + break + except error.UnknownCommand, inst: + i = inst + if i: + raise i + else: + # program name + if not ui.quiet: + rst = [_("Mercurial Distributed SCM\n"), '\n'] + rst.extend(helplist()) + + return ''.join(rst)