Mercurial > public > mercurial-scm > hg-stable

annotate mercurial/help.py @ 17837:b623e323c561

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
help: indicate help omitting if help document is not fully displayed Before this patch, there is no information about whether help document is fully displayed or not. So, some users seem to misunderstand "-v" for "hg help" just as "the option to show list of global options": experience on "hg help -v" for some commands not containing verbose containers may strengthen this misunderstanding. Such users have less opportunity for noticing omitted help document, and this may cause insufficient understanding about Mercurial. This patch indicates help omitting, if help document is not fully displayed. For command help, the message below is displayed at the end of help output, if help document is not fully displayed: use "hg -v help xxxx" to show more complete help and the global options and otherwise: use "hg -v help xxxx" to show the global options For topics and extensions help, the message below is displayed, only if help document is not fully displayed: use "hg help -v xxxx" to show more complete help This allows users to know whether there is any omitted information or not exactly, and can trigger "hg help -v" invocation. This patch causes formatting help document twice, to switch messages one for omitted help, and another for not omitted. This decreases performance of help document formatting, but it is not mainly focused at help command invocation, so this wouldn't become problem.
author FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
date Thu, 18 Oct 2012 10:31:15 +0900
parents 2be2a070f294
children c0087d48ec3a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
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'''
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
15 rst = []
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
16 if exts:
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
17 rst.append('\n%s\n\n' % header)
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
18 for name, desc in sorted(exts.iteritems()):
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
19 rst.append('%s:%s: %s\n' % (' ' * indent, name, desc))
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
20 return rst
8864
cad6370a15cb help: refactor extensions listing, and show enabled ones in the dedicated topic
C?dric Duval <cedricduval@free.fr>
parents: 8863
diff changeset
21
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
22 def extshelp():
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
23 rst = loaddoc('extensions')().splitlines(True)
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
24 rst.extend(listexts(_('enabled extensions:'), extensions.enabled()))
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
25 rst.extend(listexts(_('disabled extensions:'), extensions.disabled()))
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
26 doc = ''.join(rst)
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
27 return doc
7013
f56e788fa292 i18n: mark help strings for translation
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
28
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
29 def optrst(options, verbose):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
30 data = []
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
31 multioccur = False
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
32 for option in options:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
33 if len(option) == 5:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
34 shortopt, longopt, default, desc, optlabel = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
35 else:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
36 shortopt, longopt, default, desc = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
37 optlabel = _("VALUE") # default label
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
38
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
39 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
40 continue
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
41
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
42 so = ''
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
43 if shortopt:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
44 so = '-' + shortopt
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
45 lo = '--' + longopt
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
46 if default:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
47 desc += _(" (default: %s)") % default
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
48
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
49 if isinstance(default, list):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
50 lo += " %s [+]" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
51 multioccur = True
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
52 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
53 lo += " %s" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
54
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
55 data.append((so, lo, desc))
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
56
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
57 rst = minirst.maketable(data, 1)
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
58
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
59 if multioccur:
16815
e740746ea557 minirst: generate tables as a list of joined lines
Olav Reinert <seroton10@gmail.com>
parents: 16781
diff changeset
60 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
61
16815
e740746ea557 minirst: generate tables as a list of joined lines
Olav Reinert <seroton10@gmail.com>
parents: 16781
diff changeset
62 return ''.join(rst)
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
63
17837
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
64 def indicateomitted(rst, omitted, notomitted=None):
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
65 rst.append('\n\n.. container:: omitted\n\n %s\n\n' % omitted)
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
66 if notomitted:
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
67 rst.append('\n\n.. container:: notomitted\n\n %s\n\n' % notomitted)
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
68
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
69 def topicmatch(kw):
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
70 """Return help topics matching kw.
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
71
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
72 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
73 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
74 """
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
75 kw = encoding.lower(kw)
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
76 def lowercontains(container):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
77 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
78 results = {'topics': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
79 'commands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
80 'extensions': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
81 'extensioncommands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
82 }
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
83 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
84 if (sum(map(lowercontains, names))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
85 or lowercontains(header)
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
86 or lowercontains(doc())):
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
87 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
88 import commands # avoid cycle
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
89 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
90 if cmd.startswith('debug'):
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
91 continue
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
92 if len(entry) == 3:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
93 summary = entry[2]
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
94 else:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
95 summary = ''
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
96 # 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
97 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
98 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
99 doclines = docs.splitlines()
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
100 if doclines:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
101 summary = doclines[0]
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
102 cmdname = cmd.split('|')[0].lstrip('^')
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
103 results['commands'].append((cmdname, summary))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
104 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
105 extensions.enabled().iteritems(),
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
106 extensions.disabled().iteritems()):
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
107 # 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
108 mod = extensions.load(None, name, '')
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
109 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
110 # 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
111 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
112 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
113 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
114 cmdname = cmd.split('|')[0].lstrip('^')
16942
87882c8753d4 help: fix extension commands help in keyword search
Olav Reinert <seroton10@gmail.com>
parents: 16884
diff changeset
115 if entry[0].__doc__:
87882c8753d4 help: fix extension commands help in keyword search
Olav Reinert <seroton10@gmail.com>
parents: 16884
diff changeset
116 cmddoc = gettext(entry[0].__doc__).splitlines()[0]
16884
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
117 else:
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
118 cmddoc = _('(no help text available)')
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
119 results['extensioncommands'].append((cmdname, cmddoc))
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
120 return results
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
121
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
122 def loaddoc(topic):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
123 """Return a delayed loader for help/topic.txt."""
3798
6f0c42d50394 move environment topic
Matt Mackall <mpm@selenic.com>
parents: 3795
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 def loader():
14941
4a28cb4df1f8 windows: check util.mainfrozen() instead of ad-hoc checks everywhere
Augie Fackler <durin42@gmail.com>
parents: 14686
diff changeset
126 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
127 module = sys.executable
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
128 else:
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
129 module = __file__
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
130 base = os.path.dirname(module)
7293
3549659450e6 help: add a topic on git diffs (issue1352)
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents: 7013
diff changeset
131
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
132 for dir in ('.', '..'):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
133 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
134 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
135 break
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
136
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
137 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
138 doc = gettext(util.readfile(path))
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
139 for rewriter in helphooks.get(topic, []):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
140 doc = rewriter(topic, doc)
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
141 return doc
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
142
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
143 return loader
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
144
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
145 helptable = sorted([
12145
c407b4ca666e help: make "hg help hgrc" an alias for "hg help config"
Martin Geisler <mg@lazybytes.net>
parents: 11657
diff changeset
146 (["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
147 (["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
148 (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
149 (['environment', 'env'], _('Environment Variables'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
150 loaddoc('environment')),
17322
7124f984dc8d help: use the first topic name from helptable, not the longest alias
Mads Kiilerich <mads@kiilerich.com>
parents: 17321
diff changeset
151 (['revisions', 'revs'], _('Specifying Single Revisions'),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
152 loaddoc('revisions')),
17322
7124f984dc8d help: use the first topic name from helptable, not the longest alias
Mads Kiilerich <mads@kiilerich.com>
parents: 17321
diff changeset
153 (['multirevs', 'mrevs'], _('Specifying Multiple Revisions'),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
154 loaddoc('multirevs')),
17322
7124f984dc8d help: use the first topic name from helptable, not the longest alias
Mads Kiilerich <mads@kiilerich.com>
parents: 17321
diff changeset
155 (['revsets', 'revset'], _("Specifying Revision Sets"), loaddoc('revsets')),
7124f984dc8d help: use the first topic name from helptable, not the longest alias
Mads Kiilerich <mads@kiilerich.com>
parents: 17321
diff changeset
156 (['filesets', 'fileset'], _("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
157 (['diffs'], _('Diff Formats'), loaddoc('diffs')),
17323
2be2a070f294 help: add 'mergetools' alias for the 'merge-tools' help topic
Mads Kiilerich <mads@kiilerich.com>
parents: 17322
diff changeset
158 (['merge-tools', 'mergetools'], _('Merge Tools'), loaddoc('merge-tools')),
16568
770190bff625 help: add reference to template help (issue3413)
A. S. Budden <abudden@gmail.com>
parents: 16547
diff changeset
159 (['templating', 'templates', 'template', 'style'], _('Template Usage'),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
160 loaddoc('templates')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
161 (['urls'], _('URL Paths'), loaddoc('urls')),
16547
23072be2eaa3 help: consistently use title capitalization for help topics
Martin Geisler <mg@aragost.com>
parents: 16250
diff changeset
162 (["extensions"], _("Using Additional Features"), extshelp),
17322
7124f984dc8d help: use the first topic name from helptable, not the longest alias
Mads Kiilerich <mads@kiilerich.com>
parents: 17321
diff changeset
163 (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')),
17321
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
164 (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
165 (["glossary"], _("Glossary"), loaddoc('glossary')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
166 (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
167 loaddoc('hgignore')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
168 (["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
169 ])
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
170
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
171 # 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
172 # returning the updated version
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
173 helphooks = {}
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
174
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
175 def addtopichook(topic, rewriter):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
176 helphooks.setdefault(topic, []).append(rewriter)
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
177
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
178 def makeitemsdoc(topic, doc, marker, items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
179 """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
180 .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
181 """
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
182 entries = []
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
183 for name in sorted(items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
184 text = (items[name].__doc__ or '').rstrip()
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
185 if not text:
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
186 continue
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
187 text = gettext(text)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
188 lines = text.splitlines()
16250
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
189 doclines = [(lines[0])]
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
190 for l in lines[1:]:
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
191 # 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
192 if l.strip().startswith('>>>'):
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
193 break
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
194 doclines.append(' ' + l.strip())
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
195 entries.append('\n'.join(doclines))
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
196 entries = '\n\n'.join(entries)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
197 return doc.replace(marker, entries)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
198
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
199 def addtopicsymbols(topic, marker, symbols):
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
200 def add(topic, doc):
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
201 return makeitemsdoc(topic, doc, marker, symbols)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
202 addtopichook(topic, add)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
203
14686
6ab8b17adc03 fileset: add a help topic
Matt Mackall <mpm@selenic.com>
parents: 14318
diff changeset
204 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
205 addtopicsymbols('merge-tools', '.. internaltoolsmarker', filemerge.internals)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
206 addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols)
17187
293dd81e4601 templatekw/help: document the {parents} keyword
epriestley <hg@yghe.net>
parents: 16942
diff changeset
207 addtopicsymbols('templates', '.. keywordsmarker', templatekw.dockeywords)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
208 addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)