help: use a full header for topic titles

...for prettier HTML!

doc/gendoc.py

@@ -1,168 +1,156
 import os, sys, textwrap
 # import from the live mercurial repo
 sys.path.insert(0, "..")
 # fall back to pure modules if required C extensions are not available
 sys.path.append(os.path.join('..', 'mercurial', 'pure'))
 from mercurial import demandimport; demandimport.enable()
 from mercurial import encoding
+from mercurial import minirst
 from mercurial.commands import table, globalopts
 from mercurial.i18n import _
 from mercurial.help import helptable
 from mercurial import extensions
 from mercurial import util
 
 def get_desc(docstr):
     if not docstr:
         return "", ""
     # sanitize
     docstr = docstr.strip("\n")
     docstr = docstr.rstrip()
     shortdesc = docstr.splitlines()[0].strip()
 
     i = docstr.find("\n")
     if i != -1:
         desc = docstr[i + 2:]
     else:
         desc = shortdesc
 
     desc = textwrap.dedent(desc)
 
     return (shortdesc, desc)
 
 def get_opts(opts):
     for opt in opts:
         if len(opt) == 5:
             shortopt, longopt, default, desc, optlabel = opt
         else:
             shortopt, longopt, default, desc = opt
         allopts = []
         if shortopt:
             allopts.append("-%s" % shortopt)
         if longopt:
             allopts.append("--%s" % longopt)
         desc += default and _(" (default: %s)") % default or ""
         yield (", ".join(allopts), desc)
 
 def get_cmd(cmd, cmdtable):
     d = {}
     attr = cmdtable[cmd]
     cmds = cmd.lstrip("^").split("|")
 
     d['cmd'] = cmds[0]
     d['aliases'] = cmd.split("|")[1:]
     d['desc'] = get_desc(attr[0].__doc__)
     d['opts'] = list(get_opts(attr[1]))
 
     s = 'hg ' + cmds[0]
     if len(attr) > 2:
         if not attr[2].startswith('hg'):
             s += ' ' + attr[2]
         else:
             s = attr[2]
     d['synopsis'] = s.strip()
 
     return d
 
-def section(ui, s):
-    ui.write("%s\n%s\n\n" % (s, "\"" * encoding.colwidth(s)))
-
-def subsection(ui, s):
-    ui.write("%s\n%s\n\n" % (s, '=' * encoding.colwidth(s)))
-
-def subsubsection(ui, s):
-    ui.write("%s\n%s\n\n" % (s, "-" * encoding.colwidth(s)))
-
-def subsubsubsection(ui, s):
-    ui.write("%s\n%s\n\n" % (s, "." * encoding.colwidth(s)))
-
-
 def show_doc(ui):
     # print options
-    section(ui, _("Options"))
+    ui.write(minirst.section(_("Options")))
     for optstr, desc in get_opts(globalopts):
         ui.write("%s\n    %s\n\n" % (optstr, desc))
 
     # print cmds
-    section(ui, _("Commands"))
-    commandprinter(ui, table, subsection)
+    ui.write(minirst.section(_("Commands")))
+    commandprinter(ui, table, minirst.subsection)
 
     # print topics
     for names, sec, doc in helptable:
         if names[0] == "config":
             # The config help topic is included in the hgrc.5 man
             # page.
             continue
         for name in names:
             ui.write(".. _%s:\n" % name)
         ui.write("\n")
-        section(ui, sec)
+        ui.write(minirst.section(sec))
         if util.safehasattr(doc, '__call__'):
             doc = doc()
         ui.write(doc)
         ui.write("\n")
 
-    section(ui, _("Extensions"))
+    ui.write(minirst.section(_("Extensions")))
     ui.write(_("This section contains help for extensions that are "
                "distributed together with Mercurial. Help for other "
                "extensions is available in the help system."))
     ui.write("\n\n"
              ".. contents::\n"
              "   :class: htmlonly\n"
              "   :local:\n"
              "   :depth: 1\n\n")
 
     for extensionname in sorted(allextensionnames()):
         mod = extensions.load(None, extensionname, None)
-        subsection(ui, extensionname)
+        ui.write(minirst.subsection(extensionname))
         ui.write("%s\n\n" % mod.__doc__)
         cmdtable = getattr(mod, 'cmdtable', None)
         if cmdtable:
-            subsubsection(ui, _('Commands'))
-            commandprinter(ui, cmdtable, subsubsubsection)
+            ui.write(minirst.subsubsection(_('Commands')))
+            commandprinter(ui, cmdtable, minirst.subsubsubsection)
 
 def commandprinter(ui, cmdtable, sectionfunc):
     h = {}
     for c, attr in cmdtable.items():
         f = c.split("|")[0]
         f = f.lstrip("^")
         h[f] = c
     cmds = h.keys()
     cmds.sort()
 
     for f in cmds:
         if f.startswith("debug"):
             continue
         d = get_cmd(h[f], cmdtable)
-        sectionfunc(ui, d['cmd'])
+        ui.write(sectionfunc(d['cmd']))
         # synopsis
         ui.write("::\n\n")
         synopsislines = d['synopsis'].splitlines()
         for line in synopsislines:
             # some commands (such as rebase) have a multi-line
             # synopsis
             ui.write("   %s\n" % line)
         ui.write('\n')
         # description
         ui.write("%s\n\n" % d['desc'][1])
         # options
         opt_output = list(d['opts'])
         if opt_output:
             opts_len = max([len(line[0]) for line in opt_output])
             ui.write(_("Options:\n\n"))
             for optstr, desc in opt_output:
                 if desc:
                     s = "%-*s  %s" % (opts_len, optstr, desc)
                 else:
                     s = optstr
                 ui.write("%s\n" % s)
             ui.write("\n")
         # aliases
         if d['aliases']:
             ui.write(_("    aliases: %s\n\n") % " ".join(d['aliases']))
 
 
 def allextensionnames():
     return extensions.enabled().keys() + extensions.disabled().keys()
 
 if __name__ == "__main__":
     show_doc(sys.stdout)

mercurial/help.py

@@ -1,503 +1,504
 # 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, 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'''
     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)
 
 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]
+        rst = [minirst.section(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)

mercurial/minirst.py

@@ -1,677 +1,689
 # minirst.py - minimal reStructuredText parser
 #
 # Copyright 2009, 2010 Matt Mackall <[e-mail]> and others
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 """simplified reStructuredText parser.
 
 This parser knows just enough about reStructuredText to parse the
 Mercurial docstrings.
 
 It cheats in a major way: nested blocks are not really nested. They
 are just indented blocks that look like they are nested. This relies
 on the user to keep the right indentation for the blocks.
 
 Remember to update http://mercurial.selenic.com/wiki/HelpStyleGuide
 when adding support for new constructs.
 """
 
 import re
 import util, encoding
 from i18n import _
 
+def section(s):
+    return "%s\n%s\n\n" % (s, "\"" * encoding.colwidth(s))
+
+def subsection(s):
+    return "%s\n%s\n\n" % (s, '=' * encoding.colwidth(s))
+
+def subsubsection(s):
+    return "%s\n%s\n\n" % (s, "-" * encoding.colwidth(s))
+
+def subsubsubsection(s):
+    return "%s\n%s\n\n" % (s, "." * encoding.colwidth(s))
+
 def replace(text, substs):
     '''
     Apply a list of (find, replace) pairs to a text.
 
     >>> replace("foo bar", [('f', 'F'), ('b', 'B')])
     'Foo Bar'
     >>> encoding.encoding = 'latin1'
     >>> replace('\\x81\\\\', [('\\\\', '/')])
     '\\x81/'
     >>> encoding.encoding = 'shiftjis'
     >>> replace('\\x81\\\\', [('\\\\', '/')])
     '\\x81\\\\'
     '''
 
     # some character encodings (cp932 for Japanese, at least) use
     # ASCII characters other than control/alphabet/digit as a part of
     # multi-bytes characters, so direct replacing with such characters
     # on strings in local encoding causes invalid byte sequences.
     utext = text.decode(encoding.encoding)
     for f, t in substs:
         utext = utext.replace(f, t)
     return utext.encode(encoding.encoding)
 
 _blockre = re.compile(r"\n(?:\s*\n)+")
 
 def findblocks(text):
     """Find continuous blocks of lines in text.
 
     Returns a list of dictionaries representing the blocks. Each block
     has an 'indent' field and a 'lines' field.
     """
     blocks = []
     for b in _blockre.split(text.lstrip('\n').rstrip()):
         lines = b.splitlines()
         if lines:
             indent = min((len(l) - len(l.lstrip())) for l in lines)
             lines = [l[indent:] for l in lines]
             blocks.append(dict(indent=indent, lines=lines))
     return blocks
 
 def findliteralblocks(blocks):
     """Finds literal blocks and adds a 'type' field to the blocks.
 
     Literal blocks are given the type 'literal', all other blocks are
     given type the 'paragraph'.
     """
     i = 0
     while i < len(blocks):
         # Searching for a block that looks like this:
         #
         # +------------------------------+
         # | paragraph                    |
         # | (ends with "::")             |
         # +------------------------------+
         #    +---------------------------+
         #    | indented literal block    |
         #    +---------------------------+
         blocks[i]['type'] = 'paragraph'
         if blocks[i]['lines'][-1].endswith('::') and i + 1 < len(blocks):
             indent = blocks[i]['indent']
             adjustment = blocks[i + 1]['indent'] - indent
 
             if blocks[i]['lines'] == ['::']:
                 # Expanded form: remove block
                 del blocks[i]
                 i -= 1
             elif blocks[i]['lines'][-1].endswith(' ::'):
                 # Partially minimized form: remove space and both
                 # colons.
                 blocks[i]['lines'][-1] = blocks[i]['lines'][-1][:-3]
             else:
                 # Fully minimized form: remove just one colon.
                 blocks[i]['lines'][-1] = blocks[i]['lines'][-1][:-1]
 
             # List items are formatted with a hanging indent. We must
             # correct for this here while we still have the original
             # information on the indentation of the subsequent literal
             # blocks available.
             m = _bulletre.match(blocks[i]['lines'][0])
             if m:
                 indent += m.end()
                 adjustment -= m.end()
 
             # Mark the following indented blocks.
             while i + 1 < len(blocks) and blocks[i + 1]['indent'] > indent:
                 blocks[i + 1]['type'] = 'literal'
                 blocks[i + 1]['indent'] -= adjustment
                 i += 1
         i += 1
     return blocks
 
 _bulletre = re.compile(r'(-|[0-9A-Za-z]+\.|\(?[0-9A-Za-z]+\)|\|) ')
 _optionre = re.compile(r'^(-([a-zA-Z0-9]), )?(--[a-z0-9-]+)'
                        r'((.*)  +)(.*)$')
 _fieldre = re.compile(r':(?![: ])([^:]*)(?<! ):[ ]+(.*)')
 _definitionre = re.compile(r'[^ ]')
 _tablere = re.compile(r'(=+\s+)*=+')
 
 def splitparagraphs(blocks):
     """Split paragraphs into lists."""
     # Tuples with (list type, item regexp, single line items?). Order
     # matters: definition lists has the least specific regexp and must
     # come last.
     listtypes = [('bullet', _bulletre, True),
                  ('option', _optionre, True),
                  ('field', _fieldre, True),
                  ('definition', _definitionre, False)]
 
     def match(lines, i, itemre, singleline):
         """Does itemre match an item at line i?
 
         A list item can be followed by an indented line or another list
         item (but only if singleline is True).
         """
         line1 = lines[i]
         line2 = i + 1 < len(lines) and lines[i + 1] or ''
         if not itemre.match(line1):
             return False
         if singleline:
             return line2 == '' or line2[0] == ' ' or itemre.match(line2)
         else:
             return line2.startswith(' ')
 
     i = 0
     while i < len(blocks):
         if blocks[i]['type'] == 'paragraph':
             lines = blocks[i]['lines']
             for type, itemre, singleline in listtypes:
                 if match(lines, 0, itemre, singleline):
                     items = []
                     for j, line in enumerate(lines):
                         if match(lines, j, itemre, singleline):
                             items.append(dict(type=type, lines=[],
                                               indent=blocks[i]['indent']))
                         items[-1]['lines'].append(line)
                     blocks[i:i + 1] = items
                     break
         i += 1
     return blocks
 
 _fieldwidth = 14
 
 def updatefieldlists(blocks):
     """Find key for field lists."""
     i = 0
     while i < len(blocks):
         if blocks[i]['type'] != 'field':
             i += 1
             continue
 
         j = i
         while j < len(blocks) and blocks[j]['type'] == 'field':
             m = _fieldre.match(blocks[j]['lines'][0])
             key, rest = m.groups()
             blocks[j]['lines'][0] = rest
             blocks[j]['key'] = key
             j += 1
 
         i = j + 1
 
     return blocks
 
 def updateoptionlists(blocks):
     i = 0
     while i < len(blocks):
         if blocks[i]['type'] != 'option':
             i += 1
             continue
 
         optstrwidth = 0
         j = i
         while j < len(blocks) and blocks[j]['type'] == 'option':
             m = _optionre.match(blocks[j]['lines'][0])
 
             shortoption = m.group(2)
             group3 = m.group(3)
             longoption = group3[2:].strip()
             desc = m.group(6).strip()
             longoptionarg = m.group(5).strip()
             blocks[j]['lines'][0] = desc
 
             noshortop = ''
             if not shortoption:
                 noshortop = '   '
 
             opt = "%s%s" %   (shortoption and "-%s " % shortoption or '',
                             ("%s--%s %s") % (noshortop, longoption,
                                              longoptionarg))
             opt = opt.rstrip()
             blocks[j]['optstr'] = opt
             optstrwidth = max(optstrwidth, encoding.colwidth(opt))
             j += 1
 
         for block in blocks[i:j]:
             block['optstrwidth'] = optstrwidth
         i = j + 1
     return blocks
 
 def prunecontainers(blocks, keep):
     """Prune unwanted containers.
 
     The blocks must have a 'type' field, i.e., they should have been
     run through findliteralblocks first.
     """
     pruned = []
     i = 0
     while i + 1 < len(blocks):
         # Searching for a block that looks like this:
         #
         # +-------+---------------------------+
         # | ".. container ::" type            |
         # +---+                               |
         #     | blocks                        |
         #     +-------------------------------+
         if (blocks[i]['type'] == 'paragraph' and
             blocks[i]['lines'][0].startswith('.. container::')):
             indent = blocks[i]['indent']
             adjustment = blocks[i + 1]['indent'] - indent
             containertype = blocks[i]['lines'][0][15:]
             prune = containertype not in keep
             if prune:
                 pruned.append(containertype)
 
             # Always delete "..container:: type" block
             del blocks[i]
             j = i
             i -= 1
             while j < len(blocks) and blocks[j]['indent'] > indent:
                 if prune:
                     del blocks[j]
                 else:
                     blocks[j]['indent'] -= adjustment
                     j += 1
         i += 1
     return blocks, pruned
 
 _sectionre = re.compile(r"""^([-=`:.'"~^_*+#])\1+$""")
 
 def findtables(blocks):
     '''Find simple tables
 
        Only simple one-line table elements are supported
     '''
 
     for block in blocks:
         # Searching for a block that looks like this:
         #
         # === ==== ===
         #  A    B   C
         # === ==== ===  <- optional
         #  1    2   3
         #  x    y   z
         # === ==== ===
         if (block['type'] == 'paragraph' and
             len(block['lines']) > 2 and
             _tablere.match(block['lines'][0]) and
             block['lines'][0] == block['lines'][-1]):
             block['type'] = 'table'
             block['header'] = False
             div = block['lines'][0]
 
             # column markers are ASCII so we can calculate column
             # position in bytes
             columns = [x for x in xrange(len(div))
                        if div[x] == '=' and (x == 0 or div[x - 1] == ' ')]
             rows = []
             for l in block['lines'][1:-1]:
                 if l == div:
                     block['header'] = True
                     continue
                 row = []
                 # we measure columns not in bytes or characters but in
                 # colwidth which makes things tricky
                 pos = columns[0] # leading whitespace is bytes
                 for n, start in enumerate(columns):
                     if n + 1 < len(columns):
                         width = columns[n + 1] - start
                         v = encoding.getcols(l, pos, width) # gather columns
                         pos += len(v) # calculate byte position of end
                         row.append(v.strip())
                     else:
                         row.append(l[pos:].strip())
                 rows.append(row)
 
             block['table'] = rows
 
     return blocks
 
 def findsections(blocks):
     """Finds sections.
 
     The blocks must have a 'type' field, i.e., they should have been
     run through findliteralblocks first.
     """
     for block in blocks:
         # Searching for a block that looks like this:
         #
         # +------------------------------+
         # | Section title                |
         # | -------------                |
         # +------------------------------+
         if (block['type'] == 'paragraph' and
             len(block['lines']) == 2 and
             encoding.colwidth(block['lines'][0]) == len(block['lines'][1]) and
             _sectionre.match(block['lines'][1])):
             block['underline'] = block['lines'][1][0]
             block['type'] = 'section'
             del block['lines'][1]
     return blocks
 
 def inlineliterals(blocks):
     substs = [('``', '"')]
     for b in blocks:
         if b['type'] in ('paragraph', 'section'):
             b['lines'] = [replace(l, substs) for l in b['lines']]
     return blocks
 
 def hgrole(blocks):
     substs = [(':hg:`', '"hg '), ('`', '"')]
     for b in blocks:
         if b['type'] in ('paragraph', 'section'):
             # Turn :hg:`command` into "hg command". This also works
             # when there is a line break in the command and relies on
             # the fact that we have no stray back-quotes in the input
             # (run the blocks through inlineliterals first).
             b['lines'] = [replace(l, substs) for l in b['lines']]
     return blocks
 
 def addmargins(blocks):
     """Adds empty blocks for vertical spacing.
 
     This groups bullets, options, and definitions together with no vertical
     space between them, and adds an empty block between all other blocks.
     """
     i = 1
     while i < len(blocks):
         if (blocks[i]['type'] == blocks[i - 1]['type'] and
             blocks[i]['type'] in ('bullet', 'option', 'field')):
             i += 1
         else:
             blocks.insert(i, dict(lines=[''], indent=0, type='margin'))
             i += 2
     return blocks
 
 def prunecomments(blocks):
     """Remove comments."""
     i = 0
     while i < len(blocks):
         b = blocks[i]
         if b['type'] == 'paragraph' and (b['lines'][0].startswith('.. ') or
                                          b['lines'] == ['..']):
             del blocks[i]
             if i < len(blocks) and blocks[i]['type'] == 'margin':
                 del blocks[i]
         else:
             i += 1
     return blocks
 
 _admonitionre = re.compile(r"\.\. (admonition|attention|caution|danger|"
                            r"error|hint|important|note|tip|warning)::",
                            flags=re.IGNORECASE)
 
 def findadmonitions(blocks):
     """
     Makes the type of the block an admonition block if
     the first line is an admonition directive
     """
     i = 0
     while i < len(blocks):
         m = _admonitionre.match(blocks[i]['lines'][0])
         if m:
             blocks[i]['type'] = 'admonition'
             admonitiontitle = blocks[i]['lines'][0][3:m.end() - 2].lower()
 
             firstline = blocks[i]['lines'][0][m.end() + 1:]
             if firstline:
                 blocks[i]['lines'].insert(1, '   ' + firstline)
 
             blocks[i]['admonitiontitle'] = admonitiontitle
             del blocks[i]['lines'][0]
         i = i + 1
     return blocks
 
 _admonitiontitles = {'attention': _('Attention:'),
                      'caution': _('Caution:'),
                      'danger': _('!Danger!')  ,
                      'error': _('Error:'),
                      'hint': _('Hint:'),
                      'important': _('Important:'),
                      'note': _('Note:'),
                      'tip': _('Tip:'),
                      'warning': _('Warning!')}
 
 def formatoption(block, width):
     desc = ' '.join(map(str.strip, block['lines']))
     colwidth = encoding.colwidth(block['optstr'])
     usablewidth = width - 1
     hanging = block['optstrwidth']
     initindent = '%s%s  ' % (block['optstr'], ' ' * ((hanging - colwidth)))
     hangindent = ' ' * (encoding.colwidth(initindent) + 1)
     return ' %s\n' % (util.wrap(desc, usablewidth,
                                            initindent=initindent,
                                            hangindent=hangindent))
 
 def formatblock(block, width):
     """Format a block according to width."""
     if width <= 0:
         width = 78
     indent = ' ' * block['indent']
     if block['type'] == 'admonition':
         admonition = _admonitiontitles[block['admonitiontitle']]
         hang = len(block['lines'][-1]) - len(block['lines'][-1].lstrip())
 
         defindent = indent + hang * ' '
         text = ' '.join(map(str.strip, block['lines']))
         return '%s\n%s\n' % (indent + admonition,
                              util.wrap(text, width=width,
                                        initindent=defindent,
                                        hangindent=defindent))
     if block['type'] == 'margin':
         return '\n'
     if block['type'] == 'literal':
         indent += '  '
         return indent + ('\n' + indent).join(block['lines']) + '\n'
     if block['type'] == 'section':
         underline = encoding.colwidth(block['lines'][0]) * block['underline']
         return "%s%s\n%s%s\n" % (indent, block['lines'][0],indent, underline)
     if block['type'] == 'table':
         table = block['table']
         # compute column widths
         widths = [max([encoding.colwidth(e) for e in c]) for c in zip(*table)]
         text = ''
         span = sum(widths) + len(widths) - 1
         indent = ' ' * block['indent']
         hang = ' ' * (len(indent) + span - widths[-1])
 
         for row in table:
             l = []
             for w, v in zip(widths, row):
                 pad = ' ' * (w - encoding.colwidth(v))
                 l.append(v + pad)
             l = ' '.join(l)
             l = util.wrap(l, width=width, initindent=indent, hangindent=hang)
             if not text and block['header']:
                 text = l + '\n' + indent + '-' * (min(width, span)) + '\n'
             else:
                 text += l + "\n"
         return text
     if block['type'] == 'definition':
         term = indent + block['lines'][0]
         hang = len(block['lines'][-1]) - len(block['lines'][-1].lstrip())
         defindent = indent + hang * ' '
         text = ' '.join(map(str.strip, block['lines'][1:]))
         return '%s\n%s\n' % (term, util.wrap(text, width=width,
                                              initindent=defindent,
                                              hangindent=defindent))
     subindent = indent
     if block['type'] == 'bullet':
         if block['lines'][0].startswith('| '):
             # Remove bullet for line blocks and add no extra
             # indention.
             block['lines'][0] = block['lines'][0][2:]
         else:
             m = _bulletre.match(block['lines'][0])
             subindent = indent + m.end() * ' '
     elif block['type'] == 'field':
         key = block['key']
         subindent = indent + _fieldwidth * ' '
         if len(key) + 2 > _fieldwidth:
             # key too large, use full line width
             key = key.ljust(width)
         else:
             # key fits within field width
             key = key.ljust(_fieldwidth)
         block['lines'][0] = key + block['lines'][0]
     elif block['type'] == 'option':
         return formatoption(block, width)
 
     text = ' '.join(map(str.strip, block['lines']))
     return util.wrap(text, width=width,
                      initindent=indent,
                      hangindent=subindent) + '\n'
 
 def formathtml(blocks):
     """Format RST blocks as HTML"""
 
     out = []
     headernest = ''
     listnest = []
 
     def openlist(start, level):
         if not listnest or listnest[-1][0] != start:
             listnest.append((start, level))
             out.append('<%s>\n' % start)
 
     blocks = [b for b in blocks if b['type'] != 'margin']
 
     for pos, b in enumerate(blocks):
         btype = b['type']
         level = b['indent']
         lines = b['lines']
 
         if btype == 'admonition':
             admonition = _admonitiontitles[b['admonitiontitle']]
             text = ' '.join(map(str.strip, lines))
             out.append('<p>\n<b>%s</b> %s\n</p>\n' % (admonition, text))
         elif btype == 'paragraph':
             out.append('<p>\n%s\n</p>\n' % '\n'.join(lines))
         elif btype == 'margin':
             pass
         elif btype == 'literal':
             out.append('<pre>\n%s\n</pre>\n' % '\n'.join(lines))
         elif btype == 'section':
             i = b['underline']
             if i not in headernest:
                 headernest += i
             level = headernest.index(i) + 1
             out.append('<h%d>%s</h%d>\n' % (level, lines[0], level))
         elif btype == 'table':
             table = b['table']
             t = []
             for row in table:
                 l = []
                 for v in zip(row):
                     if not t:
                         l.append('<th>%s</th>' % v)
                     else:
                         l.append('<td>%s</td>' % v)
                 t.append(' <tr>%s</tr>\n' % ''.join(l))
             out.append('<table>\n%s</table>\n' % ''.join(t))
         elif btype == 'definition':
             openlist('dl', level)
             term = lines[0]
             text = ' '.join(map(str.strip, lines[1:]))
             out.append(' <dt>%s\n <dd>%s\n' % (term, text))
         elif btype == 'bullet':
             bullet, head = lines[0].split(' ', 1)
             if bullet == '-':
                 openlist('ul', level)
             else:
                 openlist('ol', level)
             out.append(' <li> %s\n' % ' '.join([head] + lines[1:]))
         elif btype == 'field':
             openlist('dl', level)
             key = b['key']
             text = ' '.join(map(str.strip, lines))
             out.append(' <dt>%s\n <dd>%s\n' % (key, text))
         elif btype == 'option':
             openlist('dl', level)
             opt = b['optstr']
             desc = ' '.join(map(str.strip, lines))
             out.append(' <dt>%s\n <dd>%s\n' % (opt, desc))
 
         # close lists if indent level of next block is lower
         if listnest:
             start, level = listnest[-1]
             if pos == len(blocks) - 1:
                 out.append('</%s>\n' % start)
                 listnest.pop()
             else:
                 nb = blocks[pos + 1]
                 ni = nb['indent']
                 if (ni < level or
                     (ni == level and
                      nb['type'] not in 'definition bullet field option')):
                     out.append('</%s>\n' % start)
                     listnest.pop()
 
     return ''.join(out)
 
 def parse(text, indent=0, keep=None):
     """Parse text into a list of blocks"""
     pruned = []
     blocks = findblocks(text)
     for b in blocks:
         b['indent'] += indent
     blocks = findliteralblocks(blocks)
     blocks = findtables(blocks)
     blocks, pruned = prunecontainers(blocks, keep or [])
     blocks = findsections(blocks)
     blocks = inlineliterals(blocks)
     blocks = hgrole(blocks)
     blocks = splitparagraphs(blocks)
     blocks = updatefieldlists(blocks)
     blocks = updateoptionlists(blocks)
     blocks = addmargins(blocks)
     blocks = prunecomments(blocks)
     blocks = findadmonitions(blocks)
     return blocks, pruned
 
 def formatblocks(blocks, width):
     text = ''.join(formatblock(b, width) for b in blocks)
     return text
 
 def format(text, width=80, indent=0, keep=None, style='plain'):
     """Parse and format the text according to width."""
     blocks, pruned = parse(text, indent, keep or [])
     if style == 'html':
         text = formathtml(blocks)
     else:
         text = ''.join(formatblock(b, width) for b in blocks)
     if keep is None:
         return text
     else:
         return text, pruned
 
 def getsections(blocks):
     '''return a list of (section name, nesting level, blocks) tuples'''
     nest = ""
     level = 0
     secs = []
     for b in blocks:
         if b['type'] == 'section':
             i = b['underline']
             if i not in nest:
                 nest += i
             level = nest.index(i) + 1
             nest = nest[:level]
             secs.append((b['lines'][0], level, [b]))
         else:
             if not secs:
                 # add an initial empty section
                 secs = [('', 0, [])]
             secs[-1][2].append(b)
     return secs
 
 def decorateblocks(blocks, width):
     '''generate a list of (section name, line text) pairs for search'''
     lines = []
     for s in getsections(blocks):
         section = s[0]
         text = formatblocks(s[2], width)
         lines.append([(section, l) for l in text.splitlines(True)])
     return lines
 
 def maketable(data, indent=0, header=False):
     '''Generate an RST table for the given table data as a list of lines'''
 
     widths = [max(encoding.colwidth(e) for e in c) for c in zip(*data)]
     indent = ' ' * indent
     div = indent + ' '.join('=' * w for w in widths) + '\n'
 
     out = [div]
     for row in data:
         l = []
         for w, v in zip(widths, row):
             pad = ' ' * (w - encoding.colwidth(v))
             l.append(v + pad)
         out.append(indent + ' '.join(l) + "\n")
     if header and len(data) > 1:
         out.insert(2, div)
     out.append(div)
     return out

tests/test-extension.t

@@ -1,574 +1,575
 Test basic extension support
 
   $ cat > foobar.py <<EOF
   > import os
   > from mercurial import commands
   > 
   > def uisetup(ui):
   >     ui.write("uisetup called\\n")
   > 
   > def reposetup(ui, repo):
   >     ui.write("reposetup called for %s\\n" % os.path.basename(repo.root))
   >     ui.write("ui %s= repo.ui\\n" % (ui == repo.ui and "=" or "!"))
   > 
   > def foo(ui, *args, **kwargs):
   >     ui.write("Foo\\n")
   > 
   > def bar(ui, *args, **kwargs):
   >     ui.write("Bar\\n")
   > 
   > cmdtable = {
   >    "foo": (foo, [], "hg foo"),
   >    "bar": (bar, [], "hg bar"),
   > }
   > 
   > commands.norepo += ' bar'
   > EOF
   $ abspath=`pwd`/foobar.py
 
   $ mkdir barfoo
   $ cp foobar.py barfoo/__init__.py
   $ barfoopath=`pwd`/barfoo
 
   $ hg init a
   $ cd a
   $ echo foo > file
   $ hg add file
   $ hg commit -m 'add file'
 
   $ echo '[extensions]' >> $HGRCPATH
   $ echo "foobar = $abspath" >> $HGRCPATH
   $ hg foo
   uisetup called
   reposetup called for a
   ui == repo.ui
   Foo
 
   $ cd ..
   $ hg clone a b
   uisetup called
   reposetup called for a
   ui == repo.ui
   reposetup called for b
   ui == repo.ui
   updating to branch default
   1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
   $ hg bar
   uisetup called
   Bar
   $ echo 'foobar = !' >> $HGRCPATH
 
 module/__init__.py-style
 
   $ echo "barfoo = $barfoopath" >> $HGRCPATH
   $ cd a
   $ hg foo
   uisetup called
   reposetup called for a
   ui == repo.ui
   Foo
   $ echo 'barfoo = !' >> $HGRCPATH
 
 Check that extensions are loaded in phases:
 
   $ cat > foo.py <<EOF
   > import os
   > name = os.path.basename(__file__).rsplit('.', 1)[0]
   > print "1) %s imported" % name
   > def uisetup(ui):
   >     print "2) %s uisetup" % name
   > def extsetup():
   >     print "3) %s extsetup" % name
   > def reposetup(ui, repo):
   >    print "4) %s reposetup" % name
   > EOF
 
   $ cp foo.py bar.py
   $ echo 'foo = foo.py' >> $HGRCPATH
   $ echo 'bar = bar.py' >> $HGRCPATH
 
 Command with no output, we just want to see the extensions loaded:
 
   $ hg paths
   1) foo imported
   1) bar imported
   2) foo uisetup
   2) bar uisetup
   3) foo extsetup
   3) bar extsetup
   4) foo reposetup
   4) bar reposetup
 
 Check hgweb's load order:
 
   $ cat > hgweb.cgi <<EOF
   > #!/usr/bin/env python
   > from mercurial import demandimport; demandimport.enable()
   > from mercurial.hgweb import hgweb
   > from mercurial.hgweb import wsgicgi
   > 
   > application = hgweb('.', 'test repo')
   > wsgicgi.launch(application)
   > EOF
 
   $ REQUEST_METHOD='GET' PATH_INFO='/' SCRIPT_NAME='' QUERY_STRING='' \
   >    SERVER_PORT='80' SERVER_NAME='localhost' python hgweb.cgi \
   >    | grep '^[0-9]) ' # ignores HTML output
   1) foo imported
   1) bar imported
   2) foo uisetup
   2) bar uisetup
   3) foo extsetup
   3) bar extsetup
   4) foo reposetup
   4) bar reposetup
   4) foo reposetup
   4) bar reposetup
 
   $ echo 'foo = !' >> $HGRCPATH
   $ echo 'bar = !' >> $HGRCPATH
 
   $ cd ..
 
 hide outer repo
   $ hg init
 
   $ cat > empty.py <<EOF
   > '''empty cmdtable
   > '''
   > cmdtable = {}
   > EOF
   $ emptypath=`pwd`/empty.py
   $ echo "empty = $emptypath" >> $HGRCPATH
   $ hg help empty
   empty extension - empty cmdtable
   
   no commands defined
 
   $ echo 'empty = !' >> $HGRCPATH
 
   $ cat > debugextension.py <<EOF
   > '''only debugcommands
   > '''
   > def debugfoobar(ui, repo, *args, **opts):
   >     "yet another debug command"
   >     pass
   > 
   > def foo(ui, repo, *args, **opts):
   >     """yet another foo command
   > 
   >     This command has been DEPRECATED since forever.
   >     """
   >     pass
   > 
   > cmdtable = {
   >    "debugfoobar": (debugfoobar, (), "hg debugfoobar"),
   >    "foo": (foo, (), "hg foo")
   > }
   > EOF
   $ debugpath=`pwd`/debugextension.py
   $ echo "debugextension = $debugpath" >> $HGRCPATH
 
   $ hg help debugextension
   debugextension extension - only debugcommands
   
   no commands defined
 
   $ hg --verbose help debugextension
   debugextension extension - only debugcommands
   
   list of commands:
   
    foo           yet another foo command
   
   global options:
   
    -R --repository REPO   repository root directory or name of overlay bundle
                           file
       --cwd DIR           change working directory
    -y --noninteractive    do not prompt, automatically pick the first choice for
                           all prompts
    -q --quiet             suppress output
    -v --verbose           enable additional output
       --config CONFIG [+] set/override config option (use 'section.name=value')
       --debug             enable debugging output
       --debugger          start debugger
       --encoding ENCODE   set the charset encoding (default: ascii)
       --encodingmode MODE set the charset encoding mode (default: strict)
       --traceback         always print a traceback on exception
       --time              time how long the command takes
       --profile           print command execution profile
       --version           output version information and exit
    -h --help              display help and exit
       --hidden            consider hidden changesets
   
   [+] marked option can be specified multiple times
 
   $ hg --debug help debugextension
   debugextension extension - only debugcommands
   
   list of commands:
   
    debugfoobar   yet another debug command
    foo           yet another foo command
   
   global options:
   
    -R --repository REPO   repository root directory or name of overlay bundle
                           file
       --cwd DIR           change working directory
    -y --noninteractive    do not prompt, automatically pick the first choice for
                           all prompts
    -q --quiet             suppress output
    -v --verbose           enable additional output
       --config CONFIG [+] set/override config option (use 'section.name=value')
       --debug             enable debugging output
       --debugger          start debugger
       --encoding ENCODE   set the charset encoding (default: ascii)
       --encodingmode MODE set the charset encoding mode (default: strict)
       --traceback         always print a traceback on exception
       --time              time how long the command takes
       --profile           print command execution profile
       --version           output version information and exit
    -h --help              display help and exit
       --hidden            consider hidden changesets
   
   [+] marked option can be specified multiple times
   $ echo 'debugextension = !' >> $HGRCPATH
 
 Extension module help vs command help:
 
   $ echo 'extdiff =' >> $HGRCPATH
   $ hg help extdiff
   hg extdiff [OPT]... [FILE]...
   
   use external program to diff repository (or selected files)
   
       Show differences between revisions for the specified files, using an
       external program. The default program used is diff, with default options
       "-Npru".
   
       To select a different program, use the -p/--program option. The program
       will be passed the names of two directories to compare. To pass additional
       options to the program, use -o/--option. These will be passed before the
       names of the directories to compare.
   
       When two revision arguments are given, then changes are shown between
       those revisions. If only one revision is specified then that revision is
       compared to the working directory, and, when no revisions are specified,
       the working directory files are compared to its parent.
   
   use "hg help -e extdiff" to show help for the extdiff extension
   
   options:
   
    -p --program CMD         comparison program to run
    -o --option OPT [+]      pass option to comparison program
    -r --rev REV [+]         revision
    -c --change REV          change made by revision
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
   
   [+] marked option can be specified multiple times
   
   use "hg -v help extdiff" to show the global options
 
   $ hg help --extension extdiff
   extdiff extension - command to allow external programs to compare revisions
   
   The extdiff Mercurial extension allows you to use external programs to compare
   revisions, or revision with working directory. The external diff programs are
   called with a configurable set of options and two non-option arguments: paths
   to directories containing snapshots of files to compare.
   
   The extdiff extension also allows you to configure new diff commands, so you
   do not need to type "hg extdiff -p kdiff3" always.
   
     [extdiff]
     # add new command that runs GNU diff(1) in 'context diff' mode
     cdiff = gdiff -Nprc5
     ## or the old way:
     #cmd.cdiff = gdiff
     #opts.cdiff = -Nprc5
   
     # add new command called vdiff, runs kdiff3
     vdiff = kdiff3
   
     # add new command called meld, runs meld (no need to name twice)
     meld =
   
     # add new command called vimdiff, runs gvimdiff with DirDiff plugin
     # (see http://www.vim.org/scripts/script.php?script_id=102) Non
     # English user, be sure to put "let g:DirDiffDynamicDiffText = 1" in
     # your .vimrc
     vimdiff = gvim -f "+next" \
               "+execute 'DirDiff' fnameescape(argv(0)) fnameescape(argv(1))"
   
   Tool arguments can include variables that are expanded at runtime:
   
     $parent1, $plabel1 - filename, descriptive label of first parent
     $child,   $clabel  - filename, descriptive label of child revision
     $parent2, $plabel2 - filename, descriptive label of second parent
     $root              - repository root
     $parent is an alias for $parent1.
   
   The extdiff extension will look in your [diff-tools] and [merge-tools]
   sections for diff tool arguments, when none are specified in [extdiff].
   
     [extdiff]
     kdiff3 =
   
     [diff-tools]
     kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
   
   You can use -I/-X and list of file or directory names like normal "hg diff"
   command. The extdiff extension makes snapshots of only needed files, so
   running the external diff program will actually be pretty fast (at least
   faster than having to compare the entire tree).
   
   list of commands:
   
    extdiff       use external program to diff repository (or selected files)
   
   use "hg -v help extdiff" to show builtin aliases and global options
 
   $ echo 'extdiff = !' >> $HGRCPATH
 
 Test help topic with same name as extension
 
   $ cat > multirevs.py <<EOF
   > from mercurial import commands
   > """multirevs extension
   > Big multi-line module docstring."""
   > def multirevs(ui, repo, arg, *args, **opts):
   >     """multirevs command"""
   >     pass
   > cmdtable = {
   >    "multirevs": (multirevs, [], 'ARG')
   > }
   > commands.norepo += ' multirevs'
   > EOF
   $ echo "multirevs = multirevs.py" >> $HGRCPATH
 
   $ hg help multirevs
   Specifying Multiple Revisions
+  """""""""""""""""""""""""""""
   
       When Mercurial accepts more than one revision, they may be specified
       individually, or provided as a topologically continuous range, separated
       by the ":" character.
   
       The syntax of range notation is [BEGIN]:[END], where BEGIN and END are
       revision identifiers. Both BEGIN and END are optional. If BEGIN is not
       specified, it defaults to revision number 0. If END is not specified, it
       defaults to the tip. The range ":" thus means "all revisions".
   
       If BEGIN is greater than END, revisions are treated in reverse order.
   
       A range acts as a closed interval. This means that a range of 3:5 gives 3,
       4 and 5. Similarly, a range of 9:6 gives 9, 8, 7, and 6.
   
   use "hg help -c multirevs" to see help for the multirevs command
 
   $ hg help -c multirevs
   hg multirevs ARG
   
   multirevs command
   
   use "hg -v help multirevs" to show the global options
 
   $ hg multirevs
   hg multirevs: invalid arguments
   hg multirevs ARG
   
   multirevs command
   
   use "hg help multirevs" to show the full help text
   [255]
 
   $ echo "multirevs = !" >> $HGRCPATH
 
 Issue811: Problem loading extensions twice (by site and by user)
 
   $ debugpath=`pwd`/debugissue811.py
   $ cat > debugissue811.py <<EOF
   > '''show all loaded extensions
   > '''
   > from mercurial import extensions, commands
   > 
   > def debugextensions(ui):
   >     "yet another debug command"
   >     ui.write("%s\n" % '\n'.join([x for x, y in extensions.extensions()]))
   > 
   > cmdtable = {"debugextensions": (debugextensions, (), "hg debugextensions")}
   > commands.norepo += " debugextensions"
   > EOF
   $ echo "debugissue811 = $debugpath" >> $HGRCPATH
   $ echo "mq=" >> $HGRCPATH
   $ echo "hgext.mq=" >> $HGRCPATH
   $ echo "hgext/mq=" >> $HGRCPATH
 
 Show extensions:
 
   $ hg debugextensions
   debugissue811
   mq
 
 Disabled extension commands:
 
   $ HGRCPATH=
   $ export HGRCPATH
   $ hg help email
   'email' is provided by the following extension:
   
       patchbomb     command to send changesets as (a series of) patch emails
   
   use "hg help extensions" for information on enabling extensions
   $ hg qdel
   hg: unknown command 'qdel'
   'qdelete' is provided by the following extension:
   
       mq            manage a stack of patches
   
   use "hg help extensions" for information on enabling extensions
   [255]
   $ hg churn
   hg: unknown command 'churn'
   'churn' is provided by the following extension:
   
       churn         command to display statistics about repository history
   
   use "hg help extensions" for information on enabling extensions
   [255]
 
 Disabled extensions:
 
   $ hg help churn
   churn extension - command to display statistics about repository history
   
   use "hg help extensions" for information on enabling extensions
   $ hg help patchbomb
   patchbomb extension - command to send changesets as (a series of) patch emails
   
   use "hg help extensions" for information on enabling extensions
 
 Broken disabled extension and command:
 
   $ mkdir hgext
   $ echo > hgext/__init__.py
   $ cat > hgext/broken.py <<EOF
   > "broken extension'
   > EOF
   $ cat > path.py <<EOF
   > import os, sys
   > sys.path.insert(0, os.environ['HGEXTPATH'])
   > EOF
   $ HGEXTPATH=`pwd`
   $ export HGEXTPATH
 
   $ hg --config extensions.path=./path.py help broken
   broken extension - (no help text available)
   
   use "hg help extensions" for information on enabling extensions
 
   $ cat > hgext/forest.py <<EOF
   > cmdtable = None
   > EOF
   $ hg --config extensions.path=./path.py help foo > /dev/null
   warning: error finding commands in $TESTTMP/hgext/forest.py (glob)
   hg: unknown command 'foo'
   warning: error finding commands in $TESTTMP/hgext/forest.py (glob)
   [255]
 
   $ cat > throw.py <<EOF
   > from mercurial import cmdutil, commands
   > cmdtable = {}
   > command = cmdutil.command(cmdtable)
   > class Bogon(Exception): pass
   > 
   > @command('throw', [], 'hg throw')
   > def throw(ui, **opts):
   >     """throws an exception"""
   >     raise Bogon()
   > commands.norepo += " throw"
   > EOF
 No declared supported version, extension complains:
   $ hg --config extensions.throw=throw.py throw 2>&1 | egrep '^\*\*'
   ** Unknown exception encountered with possibly-broken third-party extension throw
   ** which supports versions unknown of Mercurial.
   ** Please disable throw and try your action again.
   ** If that fixes the bug please report it to the extension author.
   ** Python * (glob)
   ** Mercurial Distributed SCM * (glob)
   ** Extensions loaded: throw
 empty declaration of supported version, extension complains:
   $ echo "testedwith = ''" >> throw.py
   $ hg --config extensions.throw=throw.py throw 2>&1 | egrep '^\*\*'
   ** Unknown exception encountered with possibly-broken third-party extension throw
   ** which supports versions unknown of Mercurial.
   ** Please disable throw and try your action again.
   ** If that fixes the bug please report it to the extension author.
   ** Python * (glob)
   ** Mercurial Distributed SCM (*) (glob)
   ** Extensions loaded: throw
 If the extension specifies a buglink, show that:
   $ echo 'buglink = "http://example.com/bts"' >> throw.py
   $ rm -f throw.pyc throw.pyo
   $ hg --config extensions.throw=throw.py throw 2>&1 | egrep '^\*\*'
   ** Unknown exception encountered with possibly-broken third-party extension throw
   ** which supports versions unknown of Mercurial.
   ** Please disable throw and try your action again.
   ** If that fixes the bug please report it to http://example.com/bts
   ** Python * (glob)
   ** Mercurial Distributed SCM (*) (glob)
   ** Extensions loaded: throw
 If the extensions declare outdated versions, accuse the older extension first:
   $ echo "from mercurial import util" >> older.py
   $ echo "util.version = lambda:'2.2'" >> older.py
   $ echo "testedwith = '1.9.3'" >> older.py
   $ echo "testedwith = '2.1.1'" >> throw.py
   $ rm -f throw.pyc throw.pyo
   $ hg --config extensions.throw=throw.py --config extensions.older=older.py \
   >   throw 2>&1 | egrep '^\*\*'
   ** Unknown exception encountered with possibly-broken third-party extension older
   ** which supports versions 1.9.3 of Mercurial.
   ** Please disable older and try your action again.
   ** If that fixes the bug please report it to the extension author.
   ** Python * (glob)
   ** Mercurial Distributed SCM (version 2.2)
   ** Extensions loaded: throw, older
 One extension only tested with older, one only with newer versions:
   $ echo "util.version = lambda:'2.1.0'" >> older.py
   $ rm -f older.pyc older.pyo
   $ hg --config extensions.throw=throw.py --config extensions.older=older.py \
   >   throw 2>&1 | egrep '^\*\*'
   ** Unknown exception encountered with possibly-broken third-party extension older
   ** which supports versions 1.9.3 of Mercurial.
   ** Please disable older and try your action again.
   ** If that fixes the bug please report it to the extension author.
   ** Python * (glob)
   ** Mercurial Distributed SCM (version 2.1.0)
   ** Extensions loaded: throw, older
 Older extension is tested with current version, the other only with newer:
   $ echo "util.version = lambda:'1.9.3'" >> older.py
   $ rm -f older.pyc older.pyo
   $ hg --config extensions.throw=throw.py --config extensions.older=older.py \
   >   throw 2>&1 | egrep '^\*\*'
   ** Unknown exception encountered with possibly-broken third-party extension throw
   ** which supports versions 2.1.1 of Mercurial.
   ** Please disable throw and try your action again.
   ** If that fixes the bug please report it to http://example.com/bts
   ** Python * (glob)
   ** Mercurial Distributed SCM (version 1.9.3)
   ** Extensions loaded: throw, older
 
 Declare the version as supporting this hg version, show regular bts link:
   $ hgver=`python -c 'from mercurial import util; print util.version().split("+")[0]'`
   $ echo 'testedwith = """'"$hgver"'"""' >> throw.py
   $ rm -f throw.pyc throw.pyo
   $ hg --config extensions.throw=throw.py throw 2>&1 | egrep '^\*\*'
   ** unknown exception encountered, please report by visiting
   ** http://mercurial.selenic.com/wiki/BugTracker
   ** Python * (glob)
   ** Mercurial Distributed SCM (*) (glob)
   ** Extensions loaded: throw

tests/test-help.t

@@ -1,1786 +1,1787
 Short help:
 
   $ hg
   Mercurial Distributed SCM
   
   basic commands:
   
    add           add the specified files on the next commit
    annotate      show changeset information by line for each file
    clone         make a copy of an existing repository
    commit        commit the specified files or all outstanding changes
    diff          diff repository (or selected files)
    export        dump the header and diffs for one or more changesets
    forget        forget the specified files on the next commit
    init          create a new repository in the given directory
    log           show revision history of entire repository or files
    merge         merge working directory with another revision
    pull          pull changes from the specified source
    push          push changes to the specified destination
    remove        remove the specified files on the next commit
    serve         start stand-alone webserver
    status        show changed files in the working directory
    summary       summarize working directory state
    update        update working directory (or switch revisions)
   
   use "hg help" for the full list of commands or "hg -v" for details
 
   $ hg -q
    add           add the specified files on the next commit
    annotate      show changeset information by line for each file
    clone         make a copy of an existing repository
    commit        commit the specified files or all outstanding changes
    diff          diff repository (or selected files)
    export        dump the header and diffs for one or more changesets
    forget        forget the specified files on the next commit
    init          create a new repository in the given directory
    log           show revision history of entire repository or files
    merge         merge working directory with another revision
    pull          pull changes from the specified source
    push          push changes to the specified destination
    remove        remove the specified files on the next commit
    serve         start stand-alone webserver
    status        show changed files in the working directory
    summary       summarize working directory state
    update        update working directory (or switch revisions)
 
   $ hg help
   Mercurial Distributed SCM
   
   list of commands:
   
    add           add the specified files on the next commit
    addremove     add all new files, delete all missing files
    annotate      show changeset information by line for each file
    archive       create an unversioned archive of a repository revision
    backout       reverse effect of earlier changeset
    bisect        subdivision search of changesets
    bookmarks     track a line of development with movable markers
    branch        set or show the current branch name
    branches      list repository named branches
    bundle        create a changegroup file
    cat           output the current or given revision of files
    clone         make a copy of an existing repository
    commit        commit the specified files or all outstanding changes
    copy          mark files as copied for the next commit
    diff          diff repository (or selected files)
    export        dump the header and diffs for one or more changesets
    forget        forget the specified files on the next commit
    graft         copy changes from other branches onto the current branch
    grep          search for a pattern in specified files and revisions
    heads         show current repository heads or show branch heads
    help          show help for a given topic or a help overview
    identify      identify the working copy or specified revision
    import        import an ordered set of patches
    incoming      show new changesets found in source
    init          create a new repository in the given directory
    locate        locate files matching specific patterns
    log           show revision history of entire repository or files
    manifest      output the current or given revision of the project manifest
    merge         merge working directory with another revision
    outgoing      show changesets not found in the destination
    parents       show the parents of the working directory or revision
    paths         show aliases for remote repositories
    phase         set or show the current phase name
    pull          pull changes from the specified source
    push          push changes to the specified destination
    recover       roll back an interrupted transaction
    remove        remove the specified files on the next commit
    rename        rename files; equivalent of copy + remove
    resolve       redo merges or set/view the merge status of files
    revert        restore files to their checkout state
    rollback      roll back the last transaction (dangerous)
    root          print the root (top) of the current working directory
    serve         start stand-alone webserver
    showconfig    show combined config settings from all hgrc files
    status        show changed files in the working directory
    summary       summarize working directory state
    tag           add one or more tags for the current or given revision
    tags          list repository tags
    tip           show the tip revision
    unbundle      apply one or more changegroup files
    update        update working directory (or switch revisions)
    verify        verify the integrity of the repository
    version       output version and copyright information
   
   additional help topics:
   
    config        Configuration Files
    dates         Date Formats
    diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
    filesets      Specifying File Sets
    glossary      Glossary
    hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
    patterns      File Name Patterns
    phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
    templating    Template Usage
    urls          URL Paths
   
   use "hg -v help" to show builtin aliases and global options
 
   $ hg -q help
    add           add the specified files on the next commit
    addremove     add all new files, delete all missing files
    annotate      show changeset information by line for each file
    archive       create an unversioned archive of a repository revision
    backout       reverse effect of earlier changeset
    bisect        subdivision search of changesets
    bookmarks     track a line of development with movable markers
    branch        set or show the current branch name
    branches      list repository named branches
    bundle        create a changegroup file
    cat           output the current or given revision of files
    clone         make a copy of an existing repository
    commit        commit the specified files or all outstanding changes
    copy          mark files as copied for the next commit
    diff          diff repository (or selected files)
    export        dump the header and diffs for one or more changesets
    forget        forget the specified files on the next commit
    graft         copy changes from other branches onto the current branch
    grep          search for a pattern in specified files and revisions
    heads         show current repository heads or show branch heads
    help          show help for a given topic or a help overview
    identify      identify the working copy or specified revision
    import        import an ordered set of patches
    incoming      show new changesets found in source
    init          create a new repository in the given directory
    locate        locate files matching specific patterns
    log           show revision history of entire repository or files
    manifest      output the current or given revision of the project manifest
    merge         merge working directory with another revision
    outgoing      show changesets not found in the destination
    parents       show the parents of the working directory or revision
    paths         show aliases for remote repositories
    phase         set or show the current phase name
    pull          pull changes from the specified source
    push          push changes to the specified destination
    recover       roll back an interrupted transaction
    remove        remove the specified files on the next commit
    rename        rename files; equivalent of copy + remove
    resolve       redo merges or set/view the merge status of files
    revert        restore files to their checkout state
    rollback      roll back the last transaction (dangerous)
    root          print the root (top) of the current working directory
    serve         start stand-alone webserver
    showconfig    show combined config settings from all hgrc files
    status        show changed files in the working directory
    summary       summarize working directory state
    tag           add one or more tags for the current or given revision
    tags          list repository tags
    tip           show the tip revision
    unbundle      apply one or more changegroup files
    update        update working directory (or switch revisions)
    verify        verify the integrity of the repository
    version       output version and copyright information
   
   additional help topics:
   
    config        Configuration Files
    dates         Date Formats
    diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
    filesets      Specifying File Sets
    glossary      Glossary
    hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
    patterns      File Name Patterns
    phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
    templating    Template Usage
    urls          URL Paths
 
 Test short command list with verbose option
 
   $ hg -v help shortlist
   Mercurial Distributed SCM
   
   basic commands:
   
    add           add the specified files on the next commit
    annotate, blame
                  show changeset information by line for each file
    clone         make a copy of an existing repository
    commit, ci    commit the specified files or all outstanding changes
    diff          diff repository (or selected files)
    export        dump the header and diffs for one or more changesets
    forget        forget the specified files on the next commit
    init          create a new repository in the given directory
    log, history  show revision history of entire repository or files
    merge         merge working directory with another revision
    pull          pull changes from the specified source
    push          push changes to the specified destination
    remove, rm    remove the specified files on the next commit
    serve         start stand-alone webserver
    status, st    show changed files in the working directory
    summary, sum  summarize working directory state
    update, up, checkout, co
                  update working directory (or switch revisions)
   
   global options:
   
    -R --repository REPO   repository root directory or name of overlay bundle
                           file
       --cwd DIR           change working directory
    -y --noninteractive    do not prompt, automatically pick the first choice for
                           all prompts
    -q --quiet             suppress output
    -v --verbose           enable additional output
       --config CONFIG [+] set/override config option (use 'section.name=value')
       --debug             enable debugging output
       --debugger          start debugger
       --encoding ENCODE   set the charset encoding (default: ascii)
       --encodingmode MODE set the charset encoding mode (default: strict)
       --traceback         always print a traceback on exception
       --time              time how long the command takes
       --profile           print command execution profile
       --version           output version information and exit
    -h --help              display help and exit
       --hidden            consider hidden changesets
   
   [+] marked option can be specified multiple times
   
   use "hg help" for the full list of commands
 
   $ hg add -h
   hg add [OPTION]... [FILE]...
   
   add the specified files on the next commit
   
       Schedule files to be version controlled and added to the repository.
   
       The files will be added to the repository at the next commit. To undo an
       add before that, see "hg forget".
   
       If no names are given, add all files to the repository.
   
       Returns 0 if all files are successfully added.
   
   options:
   
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
    -S --subrepos            recurse into subrepositories
    -n --dry-run             do not perform actions, just print output
   
   [+] marked option can be specified multiple times
   
   use "hg -v help add" to show more complete help and the global options
 
 Verbose help for add
 
   $ hg add -hv
   hg add [OPTION]... [FILE]...
   
   add the specified files on the next commit
   
       Schedule files to be version controlled and added to the repository.
   
       The files will be added to the repository at the next commit. To undo an
       add before that, see "hg forget".
   
       If no names are given, add all files to the repository.
   
       An example showing how new (unknown) files are added automatically by "hg
       add":
   
         $ ls
         foo.c
         $ hg status
         ? foo.c
         $ hg add
         adding foo.c
         $ hg status
         A foo.c
   
       Returns 0 if all files are successfully added.
   
   options:
   
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
    -S --subrepos            recurse into subrepositories
    -n --dry-run             do not perform actions, just print output
   
   [+] marked option can be specified multiple times
   
   global options:
   
    -R --repository REPO   repository root directory or name of overlay bundle
                           file
       --cwd DIR           change working directory
    -y --noninteractive    do not prompt, automatically pick the first choice for
                           all prompts
    -q --quiet             suppress output
    -v --verbose           enable additional output
       --config CONFIG [+] set/override config option (use 'section.name=value')
       --debug             enable debugging output
       --debugger          start debugger
       --encoding ENCODE   set the charset encoding (default: ascii)
       --encodingmode MODE set the charset encoding mode (default: strict)
       --traceback         always print a traceback on exception
       --time              time how long the command takes
       --profile           print command execution profile
       --version           output version information and exit
    -h --help              display help and exit
       --hidden            consider hidden changesets
   
   [+] marked option can be specified multiple times
 
 Test help option with version option
 
   $ hg add -h --version
   Mercurial Distributed SCM (version *) (glob)
   (see http://mercurial.selenic.com for more information)
   
   Copyright (C) 2005-2012 Matt Mackall and others
   This is free software; see the source for copying conditions. There is NO
   warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 
   $ hg add --skjdfks
   hg add: option --skjdfks not recognized
   hg add [OPTION]... [FILE]...
   
   add the specified files on the next commit
   
   options:
   
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
    -S --subrepos            recurse into subrepositories
    -n --dry-run             do not perform actions, just print output
   
   [+] marked option can be specified multiple times
   
   use "hg help add" to show the full help text
   [255]
 
 Test ambiguous command help
 
   $ hg help ad
   list of commands:
   
    add           add the specified files on the next commit
    addremove     add all new files, delete all missing files
   
   use "hg -v help ad" to show builtin aliases and global options
 
 Test command without options
 
   $ hg help verify
   hg verify
   
   verify the integrity of the repository
   
       Verify the integrity of the current repository.
   
       This will perform an extensive check of the repository's integrity,
       validating the hashes and checksums of each entry in the changelog,
       manifest, and tracked files, as well as the integrity of their crosslinks
       and indices.
   
       Please see http://mercurial.selenic.com/wiki/RepositoryCorruption for more
       information about recovery from corruption of the repository.
   
       Returns 0 on success, 1 if errors are encountered.
   
   use "hg -v help verify" to show the global options
 
   $ hg help diff
   hg diff [OPTION]... ([-c REV] | [-r REV1 [-r REV2]]) [FILE]...
   
   diff repository (or selected files)
   
       Show differences between revisions for the specified files.
   
       Differences between files are shown using the unified diff format.
   
       Note:
          diff may generate unexpected results for merges, as it will default to
          comparing against the working directory's first parent changeset if no
          revisions are specified.
   
       When two revision arguments are given, then changes are shown between
       those revisions. If only one revision is specified then that revision is
       compared to the working directory, and, when no revisions are specified,
       the working directory files are compared to its parent.
   
       Alternatively you can specify -c/--change with a revision to see the
       changes in that changeset relative to its first parent.
   
       Without the -a/--text option, diff will avoid generating diffs of files it
       detects as binary. With -a, diff will generate a diff anyway, probably
       with undesirable results.
   
       Use the -g/--git option to generate diffs in the git extended diff format.
       For more information, read "hg help diffs".
   
       Returns 0 on success.
   
   options:
   
    -r --rev REV [+]         revision
    -c --change REV          change made by revision
    -a --text                treat all files as text
    -g --git                 use git extended diff format
       --nodates             omit dates from diff headers
    -p --show-function       show which function each change is in
       --reverse             produce a diff that undoes the changes
    -w --ignore-all-space    ignore white space when comparing lines
    -b --ignore-space-change ignore changes in the amount of white space
    -B --ignore-blank-lines  ignore changes whose lines are all blank
    -U --unified NUM         number of lines of context to show
       --stat                output diffstat-style summary of changes
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
    -S --subrepos            recurse into subrepositories
   
   [+] marked option can be specified multiple times
   
   use "hg -v help diff" to show more complete help and the global options
 
   $ hg help status
   hg status [OPTION]... [FILE]...
   
   aliases: st
   
   show changed files in the working directory
   
       Show status of files in the repository. If names are given, only files
       that match are shown. Files that are clean or ignored or the source of a
       copy/move operation, are not listed unless -c/--clean, -i/--ignored,
       -C/--copies or -A/--all are given. Unless options described with "show
       only ..." are given, the options -mardu are used.
   
       Option -q/--quiet hides untracked (unknown and ignored) files unless
       explicitly requested with -u/--unknown or -i/--ignored.
   
       Note:
          status may appear to disagree with diff if permissions have changed or
          a merge has occurred. The standard diff format does not report
          permission changes and diff only reports changes relative to one merge
          parent.
   
       If one revision is given, it is used as the base revision. If two
       revisions are given, the differences between them are shown. The --change
       option can also be used as a shortcut to list the changed files of a
       revision from its first parent.
   
       The codes used to show the status of files are:
   
         M = modified
         A = added
         R = removed
         C = clean
         ! = missing (deleted by non-hg command, but still tracked)
         ? = not tracked
         I = ignored
           = origin of the previous file listed as A (added)
   
       Returns 0 on success.
   
   options:
   
    -A --all                 show status of all files
    -m --modified            show only modified files
    -a --added               show only added files
    -r --removed             show only removed files
    -d --deleted             show only deleted (but tracked) files
    -c --clean               show only files without changes
    -u --unknown             show only unknown (not tracked) files
    -i --ignored             show only ignored files
    -n --no-status           hide status prefix
    -C --copies              show source of copied files
    -0 --print0              end filenames with NUL, for use with xargs
       --rev REV [+]         show difference from revision
       --change REV          list the changed files of a revision
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
    -S --subrepos            recurse into subrepositories
   
   [+] marked option can be specified multiple times
   
   use "hg -v help status" to show more complete help and the global options
 
   $ hg -q help status
   hg status [OPTION]... [FILE]...
   
   show changed files in the working directory
 
   $ hg help foo
   hg: unknown command 'foo'
   Mercurial Distributed SCM
   
   basic commands:
   
    add           add the specified files on the next commit
    annotate      show changeset information by line for each file
    clone         make a copy of an existing repository
    commit        commit the specified files or all outstanding changes
    diff          diff repository (or selected files)
    export        dump the header and diffs for one or more changesets
    forget        forget the specified files on the next commit
    init          create a new repository in the given directory
    log           show revision history of entire repository or files
    merge         merge working directory with another revision
    pull          pull changes from the specified source
    push          push changes to the specified destination
    remove        remove the specified files on the next commit
    serve         start stand-alone webserver
    status        show changed files in the working directory
    summary       summarize working directory state
    update        update working directory (or switch revisions)
   
   use "hg help" for the full list of commands or "hg -v" for details
   [255]
 
   $ hg skjdfks
   hg: unknown command 'skjdfks'
   Mercurial Distributed SCM
   
   basic commands:
   
    add           add the specified files on the next commit
    annotate      show changeset information by line for each file
    clone         make a copy of an existing repository
    commit        commit the specified files or all outstanding changes
    diff          diff repository (or selected files)
    export        dump the header and diffs for one or more changesets
    forget        forget the specified files on the next commit
    init          create a new repository in the given directory
    log           show revision history of entire repository or files
    merge         merge working directory with another revision
    pull          pull changes from the specified source
    push          push changes to the specified destination
    remove        remove the specified files on the next commit
    serve         start stand-alone webserver
    status        show changed files in the working directory
    summary       summarize working directory state
    update        update working directory (or switch revisions)
   
   use "hg help" for the full list of commands or "hg -v" for details
   [255]
 
   $ cat > helpext.py <<EOF
   > import os
   > from mercurial import commands
   > 
   > def nohelp(ui, *args, **kwargs):
   >     pass
   > 
   > cmdtable = {
   >     "nohelp": (nohelp, [], "hg nohelp"),
   > }
   > 
   > commands.norepo += ' nohelp'
   > EOF
   $ echo '[extensions]' >> $HGRCPATH
   $ echo "helpext = `pwd`/helpext.py" >> $HGRCPATH
 
 Test command with no help text
 
   $ hg help nohelp
   hg nohelp
   
   (no help text available)
   
   use "hg -v help nohelp" to show the global options
 
   $ hg help -k nohelp
   Commands:
   
    nohelp hg nohelp
   
   Extension Commands:
   
    nohelp (no help text available)
 
 Test that default list of commands omits extension commands
 
   $ hg help
   Mercurial Distributed SCM
   
   list of commands:
   
    add           add the specified files on the next commit
    addremove     add all new files, delete all missing files
    annotate      show changeset information by line for each file
    archive       create an unversioned archive of a repository revision
    backout       reverse effect of earlier changeset
    bisect        subdivision search of changesets
    bookmarks     track a line of development with movable markers
    branch        set or show the current branch name
    branches      list repository named branches
    bundle        create a changegroup file
    cat           output the current or given revision of files
    clone         make a copy of an existing repository
    commit        commit the specified files or all outstanding changes
    copy          mark files as copied for the next commit
    diff          diff repository (or selected files)
    export        dump the header and diffs for one or more changesets
    forget        forget the specified files on the next commit
    graft         copy changes from other branches onto the current branch
    grep          search for a pattern in specified files and revisions
    heads         show current repository heads or show branch heads
    help          show help for a given topic or a help overview
    identify      identify the working copy or specified revision
    import        import an ordered set of patches
    incoming      show new changesets found in source
    init          create a new repository in the given directory
    locate        locate files matching specific patterns
    log           show revision history of entire repository or files
    manifest      output the current or given revision of the project manifest
    merge         merge working directory with another revision
    outgoing      show changesets not found in the destination
    parents       show the parents of the working directory or revision
    paths         show aliases for remote repositories
    phase         set or show the current phase name
    pull          pull changes from the specified source
    push          push changes to the specified destination
    recover       roll back an interrupted transaction
    remove        remove the specified files on the next commit
    rename        rename files; equivalent of copy + remove
    resolve       redo merges or set/view the merge status of files
    revert        restore files to their checkout state
    rollback      roll back the last transaction (dangerous)
    root          print the root (top) of the current working directory
    serve         start stand-alone webserver
    showconfig    show combined config settings from all hgrc files
    status        show changed files in the working directory
    summary       summarize working directory state
    tag           add one or more tags for the current or given revision
    tags          list repository tags
    tip           show the tip revision
    unbundle      apply one or more changegroup files
    update        update working directory (or switch revisions)
    verify        verify the integrity of the repository
    version       output version and copyright information
   
   enabled extensions:
   
    helpext       (no help text available)
   
   additional help topics:
   
    config        Configuration Files
    dates         Date Formats
    diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
    filesets      Specifying File Sets
    glossary      Glossary
    hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
    patterns      File Name Patterns
    phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
    templating    Template Usage
    urls          URL Paths
   
   use "hg -v help" to show builtin aliases and global options
 
 
 
 Test list of commands with command with no help text
 
   $ hg help helpext
   helpext extension - no help text available
   
   list of commands:
   
    nohelp        (no help text available)
   
   use "hg -v help helpext" to show builtin aliases and global options
 
 Test a help topic
 
   $ hg help revs
   Specifying Single Revisions
+  """""""""""""""""""""""""""
   
       Mercurial supports several ways to specify individual revisions.
   
       A plain integer is treated as a revision number. Negative integers are
       treated as sequential offsets from the tip, with -1 denoting the tip, -2
       denoting the revision prior to the tip, and so forth.
   
       A 40-digit hexadecimal string is treated as a unique revision identifier.
   
       A hexadecimal string less than 40 characters long is treated as a unique
       revision identifier and is referred to as a short-form identifier. A
       short-form identifier is only valid if it is the prefix of exactly one
       full-length identifier.
   
       Any other string is treated as a bookmark, tag, or branch name. A bookmark
       is a movable pointer to a revision. A tag is a permanent name associated
       with a revision. A branch name denotes the tipmost revision of that
       branch. Bookmark, tag, and branch names must not contain the ":"
       character.
   
       The reserved name "tip" always identifies the most recent revision.
   
       The reserved name "null" indicates the null revision. This is the revision
       of an empty repository, and the parent of revision 0.
   
       The reserved name "." indicates the working directory parent. If no
       working directory is checked out, it is equivalent to null. If an
       uncommitted merge is in progress, "." is the revision of the first parent.
 
 Test templating help
 
   $ hg help templating | egrep '(desc|diffstat|firstline|nonempty)  '
       desc          String. The text of the changeset description.
       diffstat      String. Statistics of changes with the following format:
       firstline     Any text. Returns the first line of text.
       nonempty      Any text. Returns '(none)' if the string is empty.
 
 Test help hooks
 
   $ cat > helphook1.py <<EOF
   > from mercurial import help
   > 
   > def rewrite(topic, doc):
   >     return doc + '\nhelphook1\n'
   > 
   > def extsetup(ui):
   >     help.addtopichook('revsets', rewrite)
   > EOF
   $ cat > helphook2.py <<EOF
   > from mercurial import help
   > 
   > def rewrite(topic, doc):
   >     return doc + '\nhelphook2\n'
   > 
   > def extsetup(ui):
   >     help.addtopichook('revsets', rewrite)
   > EOF
   $ echo '[extensions]' >> $HGRCPATH
   $ echo "helphook1 = `pwd`/helphook1.py" >> $HGRCPATH
   $ echo "helphook2 = `pwd`/helphook2.py" >> $HGRCPATH
   $ hg help revsets | grep helphook
       helphook1
       helphook2
 
 Test keyword search help
 
   $ hg help -k clone
   Topics:
   
    config     Configuration Files
    extensions Using Additional Features
    glossary   Glossary
    phases     Working with Phases
    subrepos   Subrepositories
    urls       URL Paths
   
   Commands:
   
    bookmarks track a line of development with movable markers
    clone     make a copy of an existing repository
    paths     show aliases for remote repositories
    update    update working directory (or switch revisions)
   
   Extensions:
   
    relink recreates hardlinks between repository clones
   
   Extension Commands:
   
    qclone clone main and patch repository at same time
 
 Test omit indicating for help
 
   $ cat > addverboseitems.py <<EOF
   > '''extension to test omit indicating.
   > 
   > This paragraph is never omitted (for extension)
   > 
   > .. container:: verbose
   > 
   >   This paragraph is omitted,
   >   if :hg:\`help\` is invoked witout \`\`-v\`\` (for extension)
   > 
   > This paragraph is never omitted, too (for extension)
   > '''
   > 
   > from mercurial import help, commands
   > testtopic = """This paragraph is never omitted (for topic).
   > 
   > .. container:: verbose
   > 
   >   This paragraph is omitted,
   >   if :hg:\`help\` is invoked witout \`\`-v\`\` (for topic)
   > 
   > This paragraph is never omitted, too (for topic)
   > """
   > def extsetup(ui):
   >     help.helptable.append((["topic-containing-verbose"],
   >                            "This is the topic to test omit indicating.",
   >                            lambda : testtopic))
   > EOF
   $ echo '[extensions]' >> $HGRCPATH
   $ echo "addverboseitems = `pwd`/addverboseitems.py" >> $HGRCPATH
   $ hg help addverboseitems
   addverboseitems extension - extension to test omit indicating.
   
   This paragraph is never omitted (for extension)
   
   This paragraph is never omitted, too (for extension)
   
   use "hg help -v addverboseitems" to show more complete help
   
   no commands defined
   $ hg help -v addverboseitems
   addverboseitems extension - extension to test omit indicating.
   
   This paragraph is never omitted (for extension)
   
   This paragraph is omitted, if "hg help" is invoked witout "-v" (for extension)
   
   This paragraph is never omitted, too (for extension)
   
   no commands defined
   $ hg help topic-containing-verbose
   This is the topic to test omit indicating.
+  """"""""""""""""""""""""""""""""""""""""""
   
       This paragraph is never omitted (for topic).
   
       This paragraph is never omitted, too (for topic)
   
   use "hg help -v topic-containing-verbose" to show more complete help
   $ hg help -v topic-containing-verbose
   This is the topic to test omit indicating.
+  """"""""""""""""""""""""""""""""""""""""""
   
       This paragraph is never omitted (for topic).
   
       This paragraph is omitted, if "hg help" is invoked witout "-v" (for topic)
   
       This paragraph is never omitted, too (for topic)
 
 Test usage of section marks in help documents
 
   $ cd "$TESTDIR"/../doc
   $ python check-seclevel.py
   $ cd $TESTTMP
 
 #if serve
 
 Test the help pages in hgweb.
 
 Dish up an empty repo; serve it cold.
 
   $ hg init "$TESTTMP/test"
   $ hg serve -R "$TESTTMP/test" -n test -p $HGPORT -d --pid-file=hg.pid
   $ cat hg.pid >> $DAEMON_PIDS
 
   $ "$TESTDIR/get-with-headers.py" 127.0.0.1:$HGPORT "help"
   200 Script output follows
   
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US">
   <head>
   <link rel="icon" href="/static/hgicon.png" type="image/png" />
   <meta name="robots" content="index, nofollow" />
   <link rel="stylesheet" href="/static/style-paper.css" type="text/css" />
   <script type="text/javascript" src="/static/mercurial.js"></script>
   
   <title>Help: Index</title>
   </head>
   <body>
   
   <div class="container">
   <div class="menu">
   <div class="logo">
   <a href="http://mercurial.selenic.com/">
   <img src="/static/hglogo.png" alt="mercurial" /></a>
   </div>
   <ul>
   <li><a href="/shortlog">log</a></li>
   <li><a href="/graph">graph</a></li>
   <li><a href="/tags">tags</a></li>
   <li><a href="/bookmarks">bookmarks</a></li>
   <li><a href="/branches">branches</a></li>
   </ul>
   <ul>
   <li class="active">help</li>
   </ul>
   </div>
   
   <div class="main">
   <h2 class="breadcrumb"><a href="/">Mercurial</a> </h2>
   <form class="search" action="/log">
   
   <p><input name="rev" id="search1" type="text" size="30" /></p>
   <div id="hint">find changesets by author, revision,
   files, or words in the commit message</div>
   </form>
   <table class="bigtable">
   <tr><td colspan="2"><h2><a name="main" href="#topics">Topics</a></h2></td></tr>
   
   <tr><td>
   <a href="/help/config">
   config
   </a>
   </td><td>
   Configuration Files
   </td></tr>
   <tr><td>
   <a href="/help/dates">
   dates
   </a>
   </td><td>
   Date Formats
   </td></tr>
   <tr><td>
   <a href="/help/diffs">
   diffs
   </a>
   </td><td>
   Diff Formats
   </td></tr>
   <tr><td>
   <a href="/help/environment">
   environment
   </a>
   </td><td>
   Environment Variables
   </td></tr>
   <tr><td>
   <a href="/help/extensions">
   extensions
   </a>
   </td><td>
   Using Additional Features
   </td></tr>
   <tr><td>
   <a href="/help/filesets">
   filesets
   </a>
   </td><td>
   Specifying File Sets
   </td></tr>
   <tr><td>
   <a href="/help/glossary">
   glossary
   </a>
   </td><td>
   Glossary
   </td></tr>
   <tr><td>
   <a href="/help/hgignore">
   hgignore
   </a>
   </td><td>
   Syntax for Mercurial Ignore Files
   </td></tr>
   <tr><td>
   <a href="/help/hgweb">
   hgweb
   </a>
   </td><td>
   Configuring hgweb
   </td></tr>
   <tr><td>
   <a href="/help/merge-tools">
   merge-tools
   </a>
   </td><td>
   Merge Tools
   </td></tr>
   <tr><td>
   <a href="/help/multirevs">
   multirevs
   </a>
   </td><td>
   Specifying Multiple Revisions
   </td></tr>
   <tr><td>
   <a href="/help/patterns">
   patterns
   </a>
   </td><td>
   File Name Patterns
   </td></tr>
   <tr><td>
   <a href="/help/phases">
   phases
   </a>
   </td><td>
   Working with Phases
   </td></tr>
   <tr><td>
   <a href="/help/revisions">
   revisions
   </a>
   </td><td>
   Specifying Single Revisions
   </td></tr>
   <tr><td>
   <a href="/help/revsets">
   revsets
   </a>
   </td><td>
   Specifying Revision Sets
   </td></tr>
   <tr><td>
   <a href="/help/subrepos">
   subrepos
   </a>
   </td><td>
   Subrepositories
   </td></tr>
   <tr><td>
   <a href="/help/templating">
   templating
   </a>
   </td><td>
   Template Usage
   </td></tr>
   <tr><td>
   <a href="/help/urls">
   urls
   </a>
   </td><td>
   URL Paths
   </td></tr>
   <tr><td>
   <a href="/help/topic-containing-verbose">
   topic-containing-verbose
   </a>
   </td><td>
   This is the topic to test omit indicating.
   </td></tr>
   
   <tr><td colspan="2"><h2><a name="main" href="#main">Main Commands</a></h2></td></tr>
   
   <tr><td>
   <a href="/help/add">
   add
   </a>
   </td><td>
   add the specified files on the next commit
   </td></tr>
   <tr><td>
   <a href="/help/annotate">
   annotate
   </a>
   </td><td>
   show changeset information by line for each file
   </td></tr>
   <tr><td>
   <a href="/help/clone">
   clone
   </a>
   </td><td>
   make a copy of an existing repository
   </td></tr>
   <tr><td>
   <a href="/help/commit">
   commit
   </a>
   </td><td>
   commit the specified files or all outstanding changes
   </td></tr>
   <tr><td>
   <a href="/help/diff">
   diff
   </a>
   </td><td>
   diff repository (or selected files)
   </td></tr>
   <tr><td>
   <a href="/help/export">
   export
   </a>
   </td><td>
   dump the header and diffs for one or more changesets
   </td></tr>
   <tr><td>
   <a href="/help/forget">
   forget
   </a>
   </td><td>
   forget the specified files on the next commit
   </td></tr>
   <tr><td>
   <a href="/help/init">
   init
   </a>
   </td><td>
   create a new repository in the given directory
   </td></tr>
   <tr><td>
   <a href="/help/log">
   log
   </a>
   </td><td>
   show revision history of entire repository or files
   </td></tr>
   <tr><td>
   <a href="/help/merge">
   merge
   </a>
   </td><td>
   merge working directory with another revision
   </td></tr>
   <tr><td>
   <a href="/help/pull">
   pull
   </a>
   </td><td>
   pull changes from the specified source
   </td></tr>
   <tr><td>
   <a href="/help/push">
   push
   </a>
   </td><td>
   push changes to the specified destination
   </td></tr>
   <tr><td>
   <a href="/help/remove">
   remove
   </a>
   </td><td>
   remove the specified files on the next commit
   </td></tr>
   <tr><td>
   <a href="/help/serve">
   serve
   </a>
   </td><td>
   start stand-alone webserver
   </td></tr>
   <tr><td>
   <a href="/help/status">
   status
   </a>
   </td><td>
   show changed files in the working directory
   </td></tr>
   <tr><td>
   <a href="/help/summary">
   summary
   </a>
   </td><td>
   summarize working directory state
   </td></tr>
   <tr><td>
   <a href="/help/update">
   update
   </a>
   </td><td>
   update working directory (or switch revisions)
   </td></tr>
   
   <tr><td colspan="2"><h2><a name="other" href="#other">Other Commands</a></h2></td></tr>
   
   <tr><td>
   <a href="/help/addremove">
   addremove
   </a>
   </td><td>
   add all new files, delete all missing files
   </td></tr>
   <tr><td>
   <a href="/help/archive">
   archive
   </a>
   </td><td>
   create an unversioned archive of a repository revision
   </td></tr>
   <tr><td>
   <a href="/help/backout">
   backout
   </a>
   </td><td>
   reverse effect of earlier changeset
   </td></tr>
   <tr><td>
   <a href="/help/bisect">
   bisect
   </a>
   </td><td>
   subdivision search of changesets
   </td></tr>
   <tr><td>
   <a href="/help/bookmarks">
   bookmarks
   </a>
   </td><td>
   track a line of development with movable markers
   </td></tr>
   <tr><td>
   <a href="/help/branch">
   branch
   </a>
   </td><td>
   set or show the current branch name
   </td></tr>
   <tr><td>
   <a href="/help/branches">
   branches
   </a>
   </td><td>
   list repository named branches
   </td></tr>
   <tr><td>
   <a href="/help/bundle">
   bundle
   </a>
   </td><td>
   create a changegroup file
   </td></tr>
   <tr><td>
   <a href="/help/cat">
   cat
   </a>
   </td><td>
   output the current or given revision of files
   </td></tr>
   <tr><td>
   <a href="/help/copy">
   copy
   </a>
   </td><td>
   mark files as copied for the next commit
   </td></tr>
   <tr><td>
   <a href="/help/graft">
   graft
   </a>
   </td><td>
   copy changes from other branches onto the current branch
   </td></tr>
   <tr><td>
   <a href="/help/grep">
   grep
   </a>
   </td><td>
   search for a pattern in specified files and revisions
   </td></tr>
   <tr><td>
   <a href="/help/heads">
   heads
   </a>
   </td><td>
   show current repository heads or show branch heads
   </td></tr>
   <tr><td>
   <a href="/help/help">
   help
   </a>
   </td><td>
   show help for a given topic or a help overview
   </td></tr>
   <tr><td>
   <a href="/help/identify">
   identify
   </a>
   </td><td>
   identify the working copy or specified revision
   </td></tr>
   <tr><td>
   <a href="/help/import">
   import
   </a>
   </td><td>
   import an ordered set of patches
   </td></tr>
   <tr><td>
   <a href="/help/incoming">
   incoming
   </a>
   </td><td>
   show new changesets found in source
   </td></tr>
   <tr><td>
   <a href="/help/locate">
   locate
   </a>
   </td><td>
   locate files matching specific patterns
   </td></tr>
   <tr><td>
   <a href="/help/manifest">
   manifest
   </a>
   </td><td>
   output the current or given revision of the project manifest
   </td></tr>
   <tr><td>
   <a href="/help/nohelp">
   nohelp
   </a>
   </td><td>
   (no help text available)
   </td></tr>
   <tr><td>
   <a href="/help/outgoing">
   outgoing
   </a>
   </td><td>
   show changesets not found in the destination
   </td></tr>
   <tr><td>
   <a href="/help/parents">
   parents
   </a>
   </td><td>
   show the parents of the working directory or revision
   </td></tr>
   <tr><td>
   <a href="/help/paths">
   paths
   </a>
   </td><td>
   show aliases for remote repositories
   </td></tr>
   <tr><td>
   <a href="/help/phase">
   phase
   </a>
   </td><td>
   set or show the current phase name
   </td></tr>
   <tr><td>
   <a href="/help/recover">
   recover
   </a>
   </td><td>
   roll back an interrupted transaction
   </td></tr>
   <tr><td>
   <a href="/help/rename">
   rename
   </a>
   </td><td>
   rename files; equivalent of copy + remove
   </td></tr>
   <tr><td>
   <a href="/help/resolve">
   resolve
   </a>
   </td><td>
   redo merges or set/view the merge status of files
   </td></tr>
   <tr><td>
   <a href="/help/revert">
   revert
   </a>
   </td><td>
   restore files to their checkout state
   </td></tr>
   <tr><td>
   <a href="/help/rollback">
   rollback
   </a>
   </td><td>
   roll back the last transaction (dangerous)
   </td></tr>
   <tr><td>
   <a href="/help/root">
   root
   </a>
   </td><td>
   print the root (top) of the current working directory
   </td></tr>
   <tr><td>
   <a href="/help/showconfig">
   showconfig
   </a>
   </td><td>
   show combined config settings from all hgrc files
   </td></tr>
   <tr><td>
   <a href="/help/tag">
   tag
   </a>
   </td><td>
   add one or more tags for the current or given revision
   </td></tr>
   <tr><td>
   <a href="/help/tags">
   tags
   </a>
   </td><td>
   list repository tags
   </td></tr>
   <tr><td>
   <a href="/help/tip">
   tip
   </a>
   </td><td>
   show the tip revision
   </td></tr>
   <tr><td>
   <a href="/help/unbundle">
   unbundle
   </a>
   </td><td>
   apply one or more changegroup files
   </td></tr>
   <tr><td>
   <a href="/help/verify">
   verify
   </a>
   </td><td>
   verify the integrity of the repository
   </td></tr>
   <tr><td>
   <a href="/help/version">
   version
   </a>
   </td><td>
   output version and copyright information
   </td></tr>
   </table>
   </div>
   </div>
   
   <script type="text/javascript">process_dates()</script>
   
   
   </body>
   </html>
   
 
   $ "$TESTDIR/get-with-headers.py" 127.0.0.1:$HGPORT "help/add"
   200 Script output follows
   
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US">
   <head>
   <link rel="icon" href="/static/hgicon.png" type="image/png" />
   <meta name="robots" content="index, nofollow" />
   <link rel="stylesheet" href="/static/style-paper.css" type="text/css" />
   <script type="text/javascript" src="/static/mercurial.js"></script>
   
   <title>Help: add</title>
   </head>
   <body>
   
   <div class="container">
   <div class="menu">
   <div class="logo">
   <a href="http://mercurial.selenic.com/">
   <img src="/static/hglogo.png" alt="mercurial" /></a>
   </div>
   <ul>
   <li><a href="/shortlog">log</a></li>
   <li><a href="/graph">graph</a></li>
   <li><a href="/tags">tags</a></li>
   <li><a href="/bookmarks">bookmarks</a></li>
   <li><a href="/branches">branches</a></li>
   </ul>
   <ul>
    <li class="active"><a href="/help">help</a></li>
   </ul>
   </div>
   
   <div class="main">
   <h2 class="breadcrumb"><a href="/">Mercurial</a> </h2>
   <h3>Help: add</h3>
   
   <form class="search" action="/log">
   
   <p><input name="rev" id="search1" type="text" size="30" /></p>
   <div id="hint">find changesets by author, revision,
   files, or words in the commit message</div>
   </form>
   <div id="doc">
   <p>
   hg add [OPTION]... [FILE]...
   </p>
   <p>
   add the specified files on the next commit
   </p>
   <p>
   Schedule files to be version controlled and added to the
   repository.
   </p>
   <p>
   The files will be added to the repository at the next commit. To
   undo an add before that, see "hg forget".
   </p>
   <p>
   If no names are given, add all files to the repository.
   </p>
   <p>
   Returns 0 if all files are successfully added.
   </p>
   <p>
   options:
   </p>
   <table>
    <tr><th>-I</th><th>--include PATTERN [+]</th><th>include names matching the given patterns</th></tr>
    <tr><td>-X</td><td>--exclude PATTERN [+]</td><td>exclude names matching the given patterns</td></tr>
    <tr><td>-S</td><td>--subrepos</td><td>recurse into subrepositories</td></tr>
    <tr><td>-n</td><td>--dry-run</td><td>do not perform actions, just print output</td></tr>
   </table>
   <p>
   [+] marked option can be specified multiple times
   </p>
   <p>
   global options:
   </p>
   <table>
    <tr><th>-R</th><th>--repository REPO</th><th>repository root directory or name of overlay bundle file</th></tr>
    <tr><td></td><td>--cwd DIR</td><td>change working directory</td></tr>
    <tr><td>-y</td><td>--noninteractive</td><td>do not prompt, automatically pick the first choice for all prompts</td></tr>
    <tr><td>-q</td><td>--quiet</td><td>suppress output</td></tr>
    <tr><td>-v</td><td>--verbose</td><td>enable additional output</td></tr>
    <tr><td></td><td>--config CONFIG [+]</td><td>set/override config option (use 'section.name=value')</td></tr>
    <tr><td></td><td>--debug</td><td>enable debugging output</td></tr>
    <tr><td></td><td>--debugger</td><td>start debugger</td></tr>
    <tr><td></td><td>--encoding ENCODE</td><td>set the charset encoding (default: ascii)</td></tr>
    <tr><td></td><td>--encodingmode MODE</td><td>set the charset encoding mode (default: strict)</td></tr>
    <tr><td></td><td>--traceback</td><td>always print a traceback on exception</td></tr>
    <tr><td></td><td>--time</td><td>time how long the command takes</td></tr>
    <tr><td></td><td>--profile</td><td>print command execution profile</td></tr>
    <tr><td></td><td>--version</td><td>output version information and exit</td></tr>
    <tr><td>-h</td><td>--help</td><td>display help and exit</td></tr>
    <tr><td></td><td>--hidden</td><td>consider hidden changesets</td></tr>
   </table>
   <p>
   [+] marked option can be specified multiple times
   </p>
   
   </div>
   </div>
   </div>
   
   <script type="text/javascript">process_dates()</script>
   
   
   </body>
   </html>
   
 
   $ "$TESTDIR/get-with-headers.py" 127.0.0.1:$HGPORT "help/remove"
   200 Script output follows
   
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US">
   <head>
   <link rel="icon" href="/static/hgicon.png" type="image/png" />
   <meta name="robots" content="index, nofollow" />
   <link rel="stylesheet" href="/static/style-paper.css" type="text/css" />
   <script type="text/javascript" src="/static/mercurial.js"></script>
   
   <title>Help: remove</title>
   </head>
   <body>
   
   <div class="container">
   <div class="menu">
   <div class="logo">
   <a href="http://mercurial.selenic.com/">
   <img src="/static/hglogo.png" alt="mercurial" /></a>
   </div>
   <ul>
   <li><a href="/shortlog">log</a></li>
   <li><a href="/graph">graph</a></li>
   <li><a href="/tags">tags</a></li>
   <li><a href="/bookmarks">bookmarks</a></li>
   <li><a href="/branches">branches</a></li>
   </ul>
   <ul>
    <li class="active"><a href="/help">help</a></li>
   </ul>
   </div>
   
   <div class="main">
   <h2 class="breadcrumb"><a href="/">Mercurial</a> </h2>
   <h3>Help: remove</h3>
   
   <form class="search" action="/log">
   
   <p><input name="rev" id="search1" type="text" size="30" /></p>
   <div id="hint">find changesets by author, revision,
   files, or words in the commit message</div>
   </form>
   <div id="doc">
   <p>
   hg remove [OPTION]... FILE...
   </p>
   <p>
   aliases: rm
   </p>
   <p>
   remove the specified files on the next commit
   </p>
   <p>
   Schedule the indicated files for removal from the current branch.
   </p>
   <p>
   This command schedules the files to be removed at the next commit.
   To undo a remove before that, see "hg revert". To undo added
   files, see "hg forget".
   </p>
   <p>
   Returns 0 on success, 1 if any warnings encountered.
   </p>
   <p>
   options:
   </p>
   <table>
    <tr><th>-A</th><th>--after</th><th>record delete for missing files</th></tr>
    <tr><td>-f</td><td>--force</td><td>remove (and delete) file even if added or modified</td></tr>
    <tr><td>-I</td><td>--include PATTERN [+]</td><td>include names matching the given patterns</td></tr>
    <tr><td>-X</td><td>--exclude PATTERN [+]</td><td>exclude names matching the given patterns</td></tr>
   </table>
   <p>
   [+] marked option can be specified multiple times
   </p>
   <p>
   global options:
   </p>
   <table>
    <tr><th>-R</th><th>--repository REPO</th><th>repository root directory or name of overlay bundle file</th></tr>
    <tr><td></td><td>--cwd DIR</td><td>change working directory</td></tr>
    <tr><td>-y</td><td>--noninteractive</td><td>do not prompt, automatically pick the first choice for all prompts</td></tr>
    <tr><td>-q</td><td>--quiet</td><td>suppress output</td></tr>
    <tr><td>-v</td><td>--verbose</td><td>enable additional output</td></tr>
    <tr><td></td><td>--config CONFIG [+]</td><td>set/override config option (use 'section.name=value')</td></tr>
    <tr><td></td><td>--debug</td><td>enable debugging output</td></tr>
    <tr><td></td><td>--debugger</td><td>start debugger</td></tr>
    <tr><td></td><td>--encoding ENCODE</td><td>set the charset encoding (default: ascii)</td></tr>
    <tr><td></td><td>--encodingmode MODE</td><td>set the charset encoding mode (default: strict)</td></tr>
    <tr><td></td><td>--traceback</td><td>always print a traceback on exception</td></tr>
    <tr><td></td><td>--time</td><td>time how long the command takes</td></tr>
    <tr><td></td><td>--profile</td><td>print command execution profile</td></tr>
    <tr><td></td><td>--version</td><td>output version information and exit</td></tr>
    <tr><td>-h</td><td>--help</td><td>display help and exit</td></tr>
    <tr><td></td><td>--hidden</td><td>consider hidden changesets</td></tr>
   </table>
   <p>
   [+] marked option can be specified multiple times
   </p>
   
   </div>
   </div>
   </div>
   
   <script type="text/javascript">process_dates()</script>
   
   
   </body>
   </html>
   
 
   $ "$TESTDIR/get-with-headers.py" 127.0.0.1:$HGPORT "help/revisions"
   200 Script output follows
   
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US">
   <head>
   <link rel="icon" href="/static/hgicon.png" type="image/png" />
   <meta name="robots" content="index, nofollow" />
   <link rel="stylesheet" href="/static/style-paper.css" type="text/css" />
   <script type="text/javascript" src="/static/mercurial.js"></script>
   
   <title>Help: revisions</title>
   </head>
   <body>
   
   <div class="container">
   <div class="menu">
   <div class="logo">
   <a href="http://mercurial.selenic.com/">
   <img src="/static/hglogo.png" alt="mercurial" /></a>
   </div>
   <ul>
   <li><a href="/shortlog">log</a></li>
   <li><a href="/graph">graph</a></li>
   <li><a href="/tags">tags</a></li>
   <li><a href="/bookmarks">bookmarks</a></li>
   <li><a href="/branches">branches</a></li>
   </ul>
   <ul>
    <li class="active"><a href="/help">help</a></li>
   </ul>
   </div>
   
   <div class="main">
   <h2 class="breadcrumb"><a href="/">Mercurial</a> </h2>
   <h3>Help: revisions</h3>
   
   <form class="search" action="/log">
   
   <p><input name="rev" id="search1" type="text" size="30" /></p>
   <div id="hint">find changesets by author, revision,
   files, or words in the commit message</div>
   </form>
   <div id="doc">
-  <p>
-  Specifying Single Revisions
-  </p>
+  <h1>Specifying Single Revisions</h1>
   <p>
   Mercurial supports several ways to specify individual revisions.
   </p>
   <p>
   A plain integer is treated as a revision number. Negative integers are
   treated as sequential offsets from the tip, with -1 denoting the tip,
   -2 denoting the revision prior to the tip, and so forth.
   </p>
   <p>
   A 40-digit hexadecimal string is treated as a unique revision
   identifier.
   </p>
   <p>
   A hexadecimal string less than 40 characters long is treated as a
   unique revision identifier and is referred to as a short-form
   identifier. A short-form identifier is only valid if it is the prefix
   of exactly one full-length identifier.
   </p>
   <p>
   Any other string is treated as a bookmark, tag, or branch name. A
   bookmark is a movable pointer to a revision. A tag is a permanent name
   associated with a revision. A branch name denotes the tipmost revision
   of that branch. Bookmark, tag, and branch names must not contain the ":"
   character.
   </p>
   <p>
   The reserved name "tip" always identifies the most recent revision.
   </p>
   <p>
   The reserved name "null" indicates the null revision. This is the
   revision of an empty repository, and the parent of revision 0.
   </p>
   <p>
   The reserved name "." indicates the working directory parent. If no
   working directory is checked out, it is equivalent to null. If an
   uncommitted merge is in progress, "." is the revision of the first
   parent.
   </p>
   
   </div>
   </div>
   </div>
   
   <script type="text/javascript">process_dates()</script>
   
   
   </body>
   </html>
   
 
   $ "$TESTDIR/killdaemons.py" $DAEMON_PIDS
 
 #endif