Mercurial > public > mercurial-scm > hg-stable

comparison mercurial/help.py @ 8879:d0a3eadfbdb3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
help: more improvements for the extensions topic - improve help text English (thanks to timeless for corrections) - rename and simplify functions a little bit, improved comments
author C?dric Duval <cedricduval@free.fr>
date Sun, 21 Jun 2009 17:52:30 +0200
parents 20a25042fadc
children a3a936a2fe46
comparison
equal deleted inserted replaced
8878:231f9d92fd7a 8879:d0a3eadfbdb3
7 7
8 from i18n import _ 8 from i18n import _
9 import extensions 9 import extensions
10 10
11 11
12 # loosely inspired by pydoc.source_synopsis()
13 # rewritten to handle ''' as well as """
14 # and to return the whole text instead of just the synopsis
15 def moduledoc(file): 12 def moduledoc(file):
16 '''Return the top python documentation for the given file''' 13 '''return the top-level python documentation for the given file
14
15 Loosely inspired by pydoc.source_synopsis(), but rewritten to handle \'''
16 as well as """ and to return the whole text instead of just the synopsis'''
17 result = [] 17 result = []
18 18
19 line = file.readline() 19 line = file.readline()
20 while line[:1] == '#' or not line.strip(): 20 while line[:1] == '#' or not line.strip():
21 line = file.readline() 21 line = file.readline()
37 else: 37 else:
38 return None 38 return None
39 39
40 return ''.join(result) 40 return ''.join(result)
41 41
42 def extensionslisting(header, exts, maxlength): 42 def listexts(header, exts, maxlength):
43 '''Return a text listing of the given extensions''' 43 '''return a text listing of the given extensions'''
44 result = '' 44 if not exts:
45 45 return ''
46 if exts: 46 result = '\n%s\n\n' % header
47 result += '\n%s\n\n' % header 47 for name, desc in sorted(exts.iteritems()):
48 for name, desc in sorted(exts.iteritems()): 48 result += ' %s %s\n' % (name.ljust(maxlength), desc)
49 result += ' %s %s\n' % (name.ljust(maxlength), desc)
50
51 return result 49 return result
52 50
53 def topicextensions(): 51 def extshelp():
54 doc = _(r''' 52 doc = _(r'''
55 Mercurial has a mechanism for adding new features through the 53 Mercurial has a mechanism for adding new features through the
56 use of extensions. Extensions may bring new commands, or new 54 use of extensions. Extensions may bring new commands, or new
57 hooks, or change some behaviors of Mercurial. 55 hooks, or change Mercurial's behavior.
58 56
59 Extensions are not loaded by default for a variety of reasons, 57 Extensions are not loaded by default for a variety of reasons,
60 they may be meant for an advanced usage or provide potentially 58 they may be meant for advanced users or provide potentially
61 dangerous commands (eg. mq or rebase allow to rewrite history), 59 dangerous commands (e.g. mq and rebase allow history to be
62 they might not be yet ready for prime-time, or they may alter 60 rewritten), they might not be ready for prime-time yet, or
63 some usual behaviors of stock Mercurial. It is thus up to the 61 they may alter Mercurial's behavior. It is thus up to the user
64 user to activate the extensions as needed. 62 to activate extensions as desired.
65 63
66 To enable an extension "foo" which is either shipped with 64 To enable the "foo" extension, either shipped with Mercurial
67 Mercurial or in the Python search path, create an entry for 65 or in the Python search path, create an entry for it in your
68 it in your hgrc, like this: 66 hgrc, like this:
69 67
70 [extensions] 68 [extensions]
71 foo = 69 foo =
72 70
73 You may also specify the full path where an extension resides: 71 You may also specify the full path to an extension:
74 72
75 [extensions] 73 [extensions]
76 myfeature = ~/.hgext/myfeature.py 74 myfeature = ~/.hgext/myfeature.py
77 75
78 To explicitly disable an extension which is enabled in an hgrc 76 To explicitly disable an extension enabled in an hgrc of broader
79 of broader scope, prepend its path with !: 77 scope, prepend its path with !:
80 78
81 [extensions] 79 [extensions]
82 # disabling extension bar residing in /ext/path 80 # disabling extension bar residing in /ext/path
83 hgext.bar = !/path/to/extension/bar.py 81 hgext.bar = !/path/to/extension/bar.py
84 # ditto, but no path was supplied for extension baz 82 # ditto, but no path was supplied for extension baz
85 hgext.baz = ! 83 hgext.baz = !
86 ''') 84 ''')
87 85
88 exts, maxlength = extensions.enabled() 86 exts, maxlength = extensions.enabled()
89 doc += extensionslisting(_('enabled extensions:'), exts, maxlength) 87 doc += listexts(_('enabled extensions:'), exts, maxlength)
90 88
91 exts, maxlength = extensions.disabled() 89 exts, maxlength = extensions.disabled()
92 doc += extensionslisting(_('non-enabled extensions:'), exts, maxlength) 90 doc += listexts(_('disabled extensions:'), exts, maxlength)
93 91
94 return doc 92 return doc
95 93
96 helptable = ( 94 helptable = (
97 (["dates"], _("Date Formats"), 95 (["dates"], _("Date Formats"),
502 500
503 default-push: 501 default-push:
504 The push command will look for a path named 'default-push', and 502 The push command will look for a path named 'default-push', and
505 prefer it over 'default' if both are defined. 503 prefer it over 'default' if both are defined.
506 ''')), 504 ''')),
507 (["extensions"], _("Using additional features"), topicextensions), 505 (["extensions"], _("Using additional features"), extshelp),
508 ) 506 )