mercurial/help.py
author Nikolaj Sjujskij <sterkrig@myopera.com>
Mon, 04 Jun 2012 10:45:56 +0400
changeset 16845 4594729c61ee
parent 16816 d10994f1c7a2
child 16852 af69b2b64d6e
permissions -rw-r--r--
help: fix search with `-k` option in non-ASCII locales Keyword search in help (introduced in 497deec204d1 and a17983680f12 by Augie Fackler) tries to translate already translated strings, which results in Unicode errors in gettext when non-ASCII locale is used. Also command descriptions should be translated before searching there (thanks to FUJIWARA Katsunori for pointing this out and actual fix), (issue3482).
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
3795
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     1
# help.py - help data for mercurial
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     2
#
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     3
# Copyright 2006 Matt Mackall <mpm@selenic.com>
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     4
#
8225
46293a0c7e9f updated license to be explicit about GPL version 2
Martin Geisler <mg@lazybytes.net>
parents: 8159
diff changeset
     5
# This software may be used and distributed according to the terms of the
10263
25e572394f5c Update license to GPLv2+
Matt Mackall <mpm@selenic.com>
parents: 9785
diff changeset
     6
# GNU General Public License version 2 or any later version.
3795
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     7
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
     8
from i18n import gettext, _
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
     9
import itertools, sys, os
16126
0c4bec9596d8 filemerge: create detail of internal merge tools from documentation string
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 15996
diff changeset
    10
import extensions, revset, fileset, templatekw, templatefilters, filemerge
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    11
import encoding, util, minirst
8863
7b19c3c0172b help: adding a new help topic about extensions
Cédric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
    12
14316
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 14168
diff changeset
    13
def listexts(header, exts, indent=1):
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
    14
    '''return a text listing of the given extensions'''
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
    15
    if not exts:
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
    16
        return ''
14316
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 14168
diff changeset
    17
    maxlength = max(len(e) for e in exts)
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
    18
    result = '\n%s\n\n' % header
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
    19
    for name, desc in sorted(exts.iteritems()):
10364
de1e7099d100 dispatch: provide help for disabled extensions and commands
Brodie Rao <me+hg@dackz.net>
parents: 10282
diff changeset
    20
        result += '%s%-*s %s\n' % (' ' * indent, maxlength + 2,
de1e7099d100 dispatch: provide help for disabled extensions and commands
Brodie Rao <me+hg@dackz.net>
parents: 10282
diff changeset
    21
                                   ':%s:' % name, desc)
8864
cad6370a15cb help: refactor extensions listing, and show enabled ones in the dedicated topic
Cédric Duval <cedricduval@free.fr>
parents: 8863
diff changeset
    22
    return result
cad6370a15cb help: refactor extensions listing, and show enabled ones in the dedicated topic
Cédric Duval <cedricduval@free.fr>
parents: 8863
diff changeset
    23
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
    24
def extshelp():
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
    25
    doc = loaddoc('extensions')()
14316
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 14168
diff changeset
    26
    doc += listexts(_('enabled extensions:'), extensions.enabled())
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 14168
diff changeset
    27
    doc += listexts(_('disabled extensions:'), extensions.disabled())
8863
7b19c3c0172b help: adding a new help topic about extensions
Cédric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
    28
    return doc
7013
f56e788fa292 i18n: mark help strings for translation
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
    29
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    30
def optrst(options, verbose):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    31
    data = []
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    32
    multioccur = False
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    33
    for option in options:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    34
        if len(option) == 5:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    35
            shortopt, longopt, default, desc, optlabel = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    36
        else:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    37
            shortopt, longopt, default, desc = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    38
            optlabel = _("VALUE") # default label
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    39
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    40
        if _("DEPRECATED") in desc and not verbose:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    41
            continue
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    42
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    43
        so = ''
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    44
        if shortopt:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    45
            so = '-' + shortopt
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    46
        lo = '--' + longopt
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    47
        if default:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    48
            desc += _(" (default: %s)") % default
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    49
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    50
        if isinstance(default, list):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    51
            lo += " %s [+]" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    52
            multioccur = True
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    53
        elif (default is not None) and not isinstance(default, bool):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    54
            lo += " %s" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    55
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    56
        data.append((so, lo, desc))
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    57
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    58
    rst = minirst.maketable(data, 1)
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    59
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    60
    if multioccur:
16815
e740746ea557 minirst: generate tables as a list of joined lines
Olav Reinert <seroton10@gmail.com>
parents: 16781
diff changeset
    61
        rst.append(_("\n[+] marked option can be specified multiple times\n"))
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    62
16815
e740746ea557 minirst: generate tables as a list of joined lines
Olav Reinert <seroton10@gmail.com>
parents: 16781
diff changeset
    63
    return ''.join(rst)
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    64
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    65
def topicmatch(kw):
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    66
    """Return help topics matching kw.
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    67
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    68
    Returns {'section': [(name, summary), ...], ...} where section is
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    69
    one of topics, commands, extensions, or extensioncommands.
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    70
    """
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    71
    kw = encoding.lower(kw)
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    72
    def lowercontains(container):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
    73
        return kw in encoding.lower(container)  # translated in helptable
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    74
    results = {'topics': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    75
               'commands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    76
               'extensions': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    77
               'extensioncommands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    78
               }
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    79
    for names, header, doc in helptable:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    80
        if (sum(map(lowercontains, names))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    81
            or lowercontains(header)
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    82
            or lowercontains(doc())):
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    83
            results['topics'].append((names[0], header))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    84
    import commands # avoid cycle
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    85
    for cmd, entry in commands.table.iteritems():
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    86
        if cmd.startswith('debug'):
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    87
            continue
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    88
        if len(entry) == 3:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    89
            summary = entry[2]
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    90
        else:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    91
            summary = ''
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
    92
        # translate docs *before* searching there
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
    93
        docs = _(getattr(entry[0], '__doc__', None)) or ''
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    94
        if kw in cmd or lowercontains(summary) or lowercontains(docs):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
    95
            doclines = docs.splitlines()
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    96
            if doclines:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    97
                summary = doclines[0]
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    98
            cmdname = cmd.split('|')[0].lstrip('^')
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
    99
            results['commands'].append((cmdname, summary))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   100
    for name, docs in itertools.chain(
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   101
        extensions.enabled().iteritems(),
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   102
        extensions.disabled().iteritems()):
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   103
        # extensions.load ignores the UI argument
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   104
        mod = extensions.load(None, name, '')
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   105
        if lowercontains(name) or lowercontains(docs):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   106
            # extension docs are already translated
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   107
            results['extensions'].append((name, docs.splitlines()[0]))
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   108
        for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems():
16711
497deec204d1 help: add --keyword (-k) for searching help
Augie Fackler <raf@durin42.com>
parents: 16710
diff changeset
   109
            if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])):
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   110
                cmdname = cmd.split('|')[0].lstrip('^')
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   111
                results['extensioncommands'].append(
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   112
                    (cmdname, _(getattr(cmd, '__doc__', ''))))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   113
    return results
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   114
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   115
def loaddoc(topic):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   116
    """Return a delayed loader for help/topic.txt."""
3798
6f0c42d50394 move environment topic
Matt Mackall <mpm@selenic.com>
parents: 3795
diff changeset
   117
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   118
    def loader():
14941
4a28cb4df1f8 windows: check util.mainfrozen() instead of ad-hoc checks everywhere
Augie Fackler <durin42@gmail.com>
parents: 14686
diff changeset
   119
        if util.mainfrozen():
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   120
            module = sys.executable
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   121
        else:
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   122
            module = __file__
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   123
        base = os.path.dirname(module)
7293
3549659450e6 help: add a topic on git diffs (issue1352)
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents: 7013
diff changeset
   124
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   125
        for dir in ('.', '..'):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   126
            docdir = os.path.join(base, dir, 'help')
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   127
            if os.path.isdir(docdir):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   128
                break
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
   129
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   130
        path = os.path.join(docdir, topic + ".txt")
14168
135e244776f0 prevent transient leaks of file handle by using new helper functions
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 14044
diff changeset
   131
        doc = gettext(util.readfile(path))
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   132
        for rewriter in helphooks.get(topic, []):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   133
            doc = rewriter(topic, doc)
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   134
        return doc
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   135
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   136
    return loader
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
   137
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
   138
helptable = sorted([
12145
c407b4ca666e help: make "hg help hgrc" an alias for "hg help config"
Martin Geisler <mg@lazybytes.net>
parents: 11657
diff changeset
   139
    (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   140
    (["dates"], _("Date Formats"), loaddoc('dates')),
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   141
    (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   142
    (['environment', 'env'], _('Environment Variables'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   143
     loaddoc('environment')),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   144
    (['revs', 'revisions'], _('Specifying Single Revisions'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   145
     loaddoc('revisions')),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   146
    (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   147
     loaddoc('multirevs')),
12818
019b8e1e0402 help: add "revset" alias for "revsets" help topic
Martin Geisler <mg@lazybytes.net>
parents: 12771
diff changeset
   148
    (['revset', 'revsets'], _("Specifying Revision Sets"), loaddoc('revsets')),
14686
6ab8b17adc03 fileset: add a help topic
Matt Mackall <mpm@selenic.com>
parents: 14318
diff changeset
   149
    (['fileset', 'filesets'], _("Specifying File Sets"), loaddoc('filesets')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   150
    (['diffs'], _('Diff Formats'), loaddoc('diffs')),
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents: 12401
diff changeset
   151
    (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools')),
16568
770190bff625 help: add reference to template help (issue3413)
A. S. Budden <abudden@gmail.com>
parents: 16547
diff changeset
   152
    (['templating', 'templates', 'template', 'style'], _('Template Usage'),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   153
     loaddoc('templates')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   154
    (['urls'], _('URL Paths'), loaddoc('urls')),
16547
23072be2eaa3 help: consistently use title capitalization for help topics
Martin Geisler <mg@aragost.com>
parents: 16250
diff changeset
   155
    (["extensions"], _("Using Additional Features"), extshelp),
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
   156
   (["subrepo", "subrepos"], _("Subrepositories"), loaddoc('subrepos')),
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
   157
   (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
   158
   (["glossary"], _("Glossary"), loaddoc('glossary')),
16547
23072be2eaa3 help: consistently use title capitalization for help topics
Martin Geisler <mg@aragost.com>
parents: 16250
diff changeset
   159
   (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
   160
    loaddoc('hgignore')),
15996
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents: 14941
diff changeset
   161
   (["phases"], _("Working with Phases"), loaddoc('phases')),
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
   162
])
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   163
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   164
# Map topics to lists of callable taking the current topic help and
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   165
# returning the updated version
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   166
helphooks = {}
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   167
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   168
def addtopichook(topic, rewriter):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   169
    helphooks.setdefault(topic, []).append(rewriter)
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   170
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   171
def makeitemsdoc(topic, doc, marker, items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   172
    """Extract docstring from the items key to function mapping, build a
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   173
    .single documentation block and use it to overwrite the marker in doc
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   174
    """
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   175
    entries = []
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   176
    for name in sorted(items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   177
        text = (items[name].__doc__ or '').rstrip()
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   178
        if not text:
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   179
            continue
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   180
        text = gettext(text)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   181
        lines = text.splitlines()
16250
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   182
        doclines = [(lines[0])]
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   183
        for l in lines[1:]:
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   184
            # Stop once we find some Python doctest
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   185
            if l.strip().startswith('>>>'):
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   186
                break
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   187
            doclines.append('  ' + l.strip())
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   188
        entries.append('\n'.join(doclines))
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   189
    entries = '\n\n'.join(entries)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   190
    return doc.replace(marker, entries)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   191
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   192
def addtopicsymbols(topic, marker, symbols):
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   193
    def add(topic, doc):
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   194
        return makeitemsdoc(topic, doc, marker, symbols)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   195
    addtopichook(topic, add)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   196
14686
6ab8b17adc03 fileset: add a help topic
Matt Mackall <mpm@selenic.com>
parents: 14318
diff changeset
   197
addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
16126
0c4bec9596d8 filemerge: create detail of internal merge tools from documentation string
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 15996
diff changeset
   198
addtopicsymbols('merge-tools', '.. internaltoolsmarker', filemerge.internals)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   199
addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   200
addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   201
addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)