|
|
# 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 itertools, sys, os
|
|
|
import extensions, revset, fileset, templatekw, templatefilters, filemerge
|
|
|
import encoding, util, minirst
|
|
|
|
|
|
def listexts(header, exts, indent=1):
|
|
|
'''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()):
|
|
|
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()))
|
|
|
rst.extend(listexts(_('disabled extensions:'), extensions.disabled()))
|
|
|
doc = ''.join(rst)
|
|
|
return doc
|
|
|
|
|
|
def optrst(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 _("DEPRECATED") in desc and not verbose:
|
|
|
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))
|
|
|
|
|
|
rst = minirst.maketable(data, 1)
|
|
|
|
|
|
if multioccur:
|
|
|
rst.append(_("\n[+] marked option can be specified multiple times\n"))
|
|
|
|
|
|
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:
|
|
|
if (sum(map(lowercontains, names))
|
|
|
or lowercontains(header)
|
|
|
or lowercontains(doc())):
|
|
|
results['topics'].append((names[0], header))
|
|
|
import commands # avoid cycle
|
|
|
for cmd, entry in commands.table.iteritems():
|
|
|
if cmd.startswith('debug'):
|
|
|
continue
|
|
|
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().iteritems(),
|
|
|
extensions.disabled().iteritems()):
|
|
|
# extensions.load ignores the UI argument
|
|
|
mod = extensions.load(None, name, '')
|
|
|
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():
|
|
|
if util.mainfrozen():
|
|
|
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(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):
|
|
|
"""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()
|
|
|
doclines = [(lines[0])]
|
|
|
for l in lines[1:]:
|
|
|
# Stop once we find some Python doctest
|
|
|
if l.strip().startswith('>>>'):
|
|
|
break
|
|
|
doclines.append(' ' + l.strip())
|
|
|
entries.append('\n'.join(doclines))
|
|
|
entries = '\n\n'.join(entries)
|
|
|
return doc.replace(marker, entries)
|
|
|
|
|
|
def addtopicsymbols(topic, marker, symbols):
|
|
|
def add(topic, doc):
|
|
|
return makeitemsdoc(topic, doc, marker, symbols)
|
|
|
addtopichook(topic, add)
|
|
|
|
|
|
addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
|
|
|
addtopicsymbols('merge-tools', '.. internaltoolsmarker', filemerge.internals)
|
|
|
addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols)
|
|
|
addtopicsymbols('templates', '.. keywordsmarker', templatekw.dockeywords)
|
|
|
addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
|
|
|
|
