Mercurial > hg-stable
view mercurial/help.py @ 13950:14d0553bd48b
help: do not show full help text for command on option errors
Example
$ hg clone --jump foo bar
hg clone: option --jump not recognized
hg clone [OPTION]... SOURCE [DEST]
make a copy of an existing repository
options:
-U --noupdate the clone will include an empty working copy (only a
repository)
-u --updaterev REV revision, tag or branch to check out
-r --rev REV [+] include the specified changeset
-b --branch BRANCH [+] clone only the specified branch
--pull use pull protocol to copy metadata
--uncompressed use uncompressed transfer (fast over LAN)
-e --ssh CMD specify ssh command to use
--remotecmd CMD specify hg command to run on the remote side
--insecure do not verify server certificate (ignoring
web.cacerts config)
[+] marked option can be specified multiple times
use "hg help clone" to show the full help text
Motivation for this change
If the user already has specified the command, he probably already knows
the command to some extent. Apparently, he has a problem with the options,
so we show him just the synopsis with the short help and the details about
the options, with a hint on the last line how to get the full help text.
Why is Mercurial better with this change?
Experts who just forgot about the details of an option don't get that
much text thrown at them, while the newbies still get a hint on the last
line how to get the full help text.
author | Adrian Buehlmann <adrian@cadifra.com> |
---|---|
date | Sun, 17 Apr 2011 11:37:11 +0200 |
parents | 9e5407a67dea |
children | 0528b69f8db4 |
line wrap: on
line source
# help.py - help data for mercurial # # Copyright 2006 Matt Mackall <mpm@selenic.com> # # 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 sys, os import extensions def moduledoc(file): '''return the top-level python documentation for the given file Loosely inspired by pydoc.source_synopsis(), but rewritten to handle triple quotes and to return the whole text instead of just the synopsis''' result = [] line = file.readline() while line[:1] == '#' or not line.strip(): line = file.readline() if not line: break start = line[:3] if start == '"""' or start == "'''": line = line[3:] while line: if line.rstrip().endswith(start): line = line.split(start)[0] if line: result.append(line) break elif not line: return None # unmatched delimiter result.append(line) line = file.readline() else: return None return ''.join(result) def listexts(header, exts, maxlength, indent=1): '''return a text listing of the given extensions''' if not exts: return '' result = '\n%s\n\n' % header for name, desc in sorted(exts.iteritems()): result += '%s%-*s %s\n' % (' ' * indent, maxlength + 2, ':%s:' % name, desc) return result def extshelp(): doc = loaddoc('extensions')() exts, maxlength = extensions.enabled() doc += listexts(_('enabled extensions:'), exts, maxlength) exts, maxlength = extensions.disabled() doc += listexts(_('disabled extensions:'), exts, maxlength) return doc def loaddoc(topic): """Return a delayed loader for help/topic.txt.""" def loader(): if hasattr(sys, 'frozen'): module = sys.executable else: module = __file__ base = os.path.dirname(module) for dir in ('.', '..'): docdir = os.path.join(base, dir, 'help') if os.path.isdir(docdir): break path = os.path.join(docdir, topic + ".txt") doc = gettext(open(path).read()) 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')), (['revs', 'revisions'], _('Specifying Single Revisions'), loaddoc('revisions')), (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'), loaddoc('multirevs')), (['revset', 'revsets'], _("Specifying Revision Sets"), loaddoc('revsets')), (['diffs'], _('Diff Formats'), loaddoc('diffs')), (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools')), (['templating', 'templates'], _('Template Usage'), loaddoc('templates')), (['urls'], _('URL Paths'), loaddoc('urls')), (["extensions"], _("Using additional features"), extshelp), (["subrepo", "subrepos"], _("Subrepositories"), loaddoc('subrepos')), (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')), (["glossary"], _("Glossary"), loaddoc('glossary')), ]) # 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): """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) lines = text.splitlines() lines[1:] = [(' ' + l.strip()) for l in lines[1:]] entries.append('\n'.join(lines)) entries = '\n\n'.join(entries) return doc.replace(marker, entries)