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.
--- a/mercurial/commands.py Thu Oct 18 23:55:15 2012 -0500
+++ b/mercurial/commands.py Thu Oct 18 10:31:15 2012 +0900
@@ -3265,8 +3265,12 @@
rst.append(_('\nuse "hg help %s" to show the full help text\n')
% name)
elif not ui.quiet:
- rst.append(_('\nuse "hg -v help %s" to show more info\n')
- % name)
+ 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
+ help.indicateomitted(rst, omitted, notomitted)
+
return rst
@@ -3369,6 +3373,11 @@
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)
+ help.indicateomitted(rst, omitted)
+
try:
cmdutil.findcmd(name, table)
rst.append(_('\nuse "hg help -c %s" to see help for '
@@ -3396,6 +3405,11 @@
rst.extend(tail.splitlines(True))
rst.append('\n')
+ if not ui.verbose:
+ omitted = (_('use "hg help -v %s" to show more complete help') %
+ name)
+ help.indicateomitted(rst, omitted)
+
if mod:
try:
ct = mod.cmdtable
@@ -3459,7 +3473,13 @@
rst.extend(helplist())
keep = ui.verbose and ['verbose'] or []
- formatted, pruned = minirst.format(''.join(rst), textwidth, keep=keep)
+ text = ''.join(rst)
+ formatted, pruned = minirst.format(text, textwidth, keep=keep)
+ if 'verbose' in pruned:
+ keep.append('omitted')
+ else:
+ keep.append('notomitted')
+ formatted, pruned = minirst.format(text, textwidth, keep=keep)
ui.write(formatted)
--- a/mercurial/help.py Thu Oct 18 23:55:15 2012 -0500
+++ b/mercurial/help.py Thu Oct 18 10:31:15 2012 +0900
@@ -61,6 +61,11 @@
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.
--- a/tests/test-convert.t Thu Oct 18 23:55:15 2012 -0500
+++ b/tests/test-convert.t Thu Oct 18 10:31:15 2012 +0900
@@ -261,7 +261,7 @@
--datesort try to sort changesets by date
--sourcesort preserve source changesets order
- use "hg -v help convert" to show more info
+ use "hg -v help convert" to show the global options
$ hg init a
$ cd a
$ echo a > a
--- a/tests/test-encoding-align.t Thu Oct 18 23:55:15 2012 -0500
+++ b/tests/test-encoding-align.t Thu Oct 18 10:31:15 2012 +0900
@@ -59,7 +59,7 @@
\xe9\x95\xb7\xe3\x81\x84\xe9\x95\xb7\xe3\x81\x84\xe5\x90\x8d\xe5\x89\x8d \xe9\x95\xb7\xe3\x81\x84\xe9\x95\xb7\xe3\x81\x84\xe5\x90\x8d\xe5\x89\x8d \xe9\x95\xb7\xe3\x81\x84\xe9\x95\xb7\xe3\x81\x84\xe5\x90\x8d\xe5\x89\x8d \xe9\x95\xb7\xe3\x81\x84\xe9\x95\xb7\xe3\x81\x84\xe5\x90\x8d\xe5\x89\x8d (esc)
\xe9\x95\xb7\xe3\x81\x84\xe9\x95\xb7\xe3\x81\x84\xe5\x90\x8d\xe5\x89\x8d (esc)
- use "hg -v help showoptlist" to show more info
+ use "hg -v help showoptlist" to show the global options
$ rm -f s; touch s
--- a/tests/test-encoding-textwrap.t Thu Oct 18 23:55:15 2012 -0500
+++ b/tests/test-encoding-textwrap.t Thu Oct 18 10:31:15 2012 +0900
@@ -67,7 +67,7 @@
\x82\xa0\x82\xa2\x82\xa4\x82\xa6\x82\xa8\x82\xa9\x82\xab\x82\xad\x82\xaf\x82\xa0\x82\xa2\x82\xa4\x82\xa6\x82\xa8\x82\xa9\x82\xab\x82\xad\x82\xaf\x82\xa0\x82\xa2\x82\xa4\x82\xa6\x82\xa8\x82\xa9\x82\xab\x82\xad\x82\xaf (esc)
\x82\xa0\x82\xa2\x82\xa4\x82\xa6\x82\xa8\x82\xa9\x82\xab\x82\xad\x82\xaf (esc)
- use "hg -v help show_full_ja" to show more info
+ use "hg -v help show_full_ja" to show the global options
(1-2) display Japanese full-width characters in utf-8
@@ -82,7 +82,7 @@
\xe3\x81\x82\xe3\x81\x84\xe3\x81\x86\xe3\x81\x88\xe3\x81\x8a\xe3\x81\x8b\xe3\x81\x8d\xe3\x81\x8f\xe3\x81\x91\xe3\x81\x82\xe3\x81\x84\xe3\x81\x86\xe3\x81\x88\xe3\x81\x8a\xe3\x81\x8b\xe3\x81\x8d\xe3\x81\x8f\xe3\x81\x91\xe3\x81\x82\xe3\x81\x84\xe3\x81\x86\xe3\x81\x88\xe3\x81\x8a\xe3\x81\x8b\xe3\x81\x8d\xe3\x81\x8f\xe3\x81\x91 (esc)
\xe3\x81\x82\xe3\x81\x84\xe3\x81\x86\xe3\x81\x88\xe3\x81\x8a\xe3\x81\x8b\xe3\x81\x8d\xe3\x81\x8f\xe3\x81\x91 (esc)
- use "hg -v help show_full_ja" to show more info
+ use "hg -v help show_full_ja" to show the global options
(1-3) display Japanese half-width characters in cp932
@@ -98,7 +98,7 @@
\xb1\xb2\xb3\xb4\xb5\xb6\xb7\xb8\xb9\xb1\xb2\xb3\xb4\xb5\xb6\xb7\xb8\xb9\xb1\xb2\xb3\xb4\xb5\xb6\xb7\xb8\xb9\xb1\xb2\xb3\xb4\xb5\xb6\xb7\xb8\xb9\xb1\xb2\xb3\xb4\xb5\xb6\xb7\xb8\xb9\xb1\xb2\xb3\xb4\xb5\xb6\xb7\xb8\xb9 (esc)
\xb1\xb2\xb3\xb4\xb5\xb6\xb7\xb8\xb9\xb1\xb2\xb3\xb4\xb5\xb6\xb7\xb8\xb9 (esc)
- use "hg -v help show_half_ja" to show more info
+ use "hg -v help show_half_ja" to show the global options
(1-4) display Japanese half-width characters in utf-8
@@ -113,7 +113,7 @@
\xef\xbd\xb1\xef\xbd\xb2\xef\xbd\xb3\xef\xbd\xb4\xef\xbd\xb5\xef\xbd\xb6\xef\xbd\xb7\xef\xbd\xb8\xef\xbd\xb9\xef\xbd\xb1\xef\xbd\xb2\xef\xbd\xb3\xef\xbd\xb4\xef\xbd\xb5\xef\xbd\xb6\xef\xbd\xb7\xef\xbd\xb8\xef\xbd\xb9\xef\xbd\xb1\xef\xbd\xb2\xef\xbd\xb3\xef\xbd\xb4\xef\xbd\xb5\xef\xbd\xb6\xef\xbd\xb7\xef\xbd\xb8\xef\xbd\xb9\xef\xbd\xb1\xef\xbd\xb2\xef\xbd\xb3\xef\xbd\xb4\xef\xbd\xb5\xef\xbd\xb6\xef\xbd\xb7\xef\xbd\xb8\xef\xbd\xb9\xef\xbd\xb1\xef\xbd\xb2\xef\xbd\xb3\xef\xbd\xb4\xef\xbd\xb5\xef\xbd\xb6\xef\xbd\xb7\xef\xbd\xb8\xef\xbd\xb9\xef\xbd\xb1\xef\xbd\xb2\xef\xbd\xb3\xef\xbd\xb4\xef\xbd\xb5\xef\xbd\xb6\xef\xbd\xb7\xef\xbd\xb8\xef\xbd\xb9 (esc)
\xef\xbd\xb1\xef\xbd\xb2\xef\xbd\xb3\xef\xbd\xb4\xef\xbd\xb5\xef\xbd\xb6\xef\xbd\xb7\xef\xbd\xb8\xef\xbd\xb9\xef\xbd\xb1\xef\xbd\xb2\xef\xbd\xb3\xef\xbd\xb4\xef\xbd\xb5\xef\xbd\xb6\xef\xbd\xb7\xef\xbd\xb8\xef\xbd\xb9 (esc)
- use "hg -v help show_half_ja" to show more info
+ use "hg -v help show_half_ja" to show the global options
@@ -134,7 +134,7 @@
\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b (esc)
\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b (esc)
- use "hg -v help show_ambig_ja" to show more info
+ use "hg -v help show_ambig_ja" to show the global options
(2-1-2) display Japanese ambiguous-width characters in utf-8
@@ -149,7 +149,7 @@
\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b (esc)
\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b (esc)
- use "hg -v help show_ambig_ja" to show more info
+ use "hg -v help show_ambig_ja" to show the global options
(2-1-3) display Russian ambiguous-width characters in cp1251
@@ -164,7 +164,7 @@
\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8 (esc)
\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8 (esc)
- use "hg -v help show_ambig_ru" to show more info
+ use "hg -v help show_ambig_ru" to show the global options
(2-1-4) display Russian ambiguous-width characters in utf-8
@@ -179,7 +179,7 @@
\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8 (esc)
\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8 (esc)
- use "hg -v help show_ambig_ru" to show more info
+ use "hg -v help show_ambig_ru" to show the global options
(2-2) treat width of ambiguous characters as wide
@@ -200,7 +200,7 @@
\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b (esc)
\x83\xbf\x83\xc0\x83\xc1\x83\xc2\x83\xd2\x83\xc4\x83\xc5\x83\xc6\x81\x9b (esc)
- use "hg -v help show_ambig_ja" to show more info
+ use "hg -v help show_ambig_ja" to show the global options
(2-2-2) display Japanese ambiguous-width characters in utf-8
@@ -218,7 +218,7 @@
\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b (esc)
\xce\xb1\xce\xb2\xce\xb3\xce\xb4\xcf\x85\xce\xb6\xce\xb7\xce\xb8\xe2\x97\x8b (esc)
- use "hg -v help show_ambig_ja" to show more info
+ use "hg -v help show_ambig_ja" to show the global options
(2-2-3) display Russian ambiguous-width characters in cp1251
@@ -236,7 +236,7 @@
\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8 (esc)
\xcd\xe0\xf1\xf2\xf0\xee\xe9\xea\xe8 (esc)
- use "hg -v help show_ambig_ru" to show more info
+ use "hg -v help show_ambig_ru" to show the global options
(2-2-4) display Russian ambiguous-width charactes in utf-8
@@ -254,6 +254,6 @@
\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8 (esc)
\xd0\x9d\xd0\xb0\xd1\x81\xd1\x82\xd1\x80\xd0\xbe\xd0\xb9\xd0\xba\xd0\xb8 (esc)
- use "hg -v help show_ambig_ru" to show more info
+ use "hg -v help show_ambig_ru" to show the global options
$ cd ..
--- a/tests/test-extdiff.t Thu Oct 18 23:55:15 2012 -0500
+++ b/tests/test-extdiff.t Thu Oct 18 10:31:15 2012 +0900
@@ -47,7 +47,7 @@
[+] marked option can be specified multiple times
- use "hg -v help falabala" to show more info
+ use "hg -v help falabala" to show the global options
$ hg ci -d '0 0' -mtest1
--- a/tests/test-extension.t Thu Oct 18 23:55:15 2012 -0500
+++ b/tests/test-extension.t Thu Oct 18 10:31:15 2012 +0900
@@ -269,7 +269,7 @@
[+] marked option can be specified multiple times
- use "hg -v help extdiff" to show more info
+ use "hg -v help extdiff" to show the global options
$ hg help --extension extdiff
extdiff extension - command to allow external programs to compare revisions
@@ -372,7 +372,7 @@
multirevs command
- use "hg -v help multirevs" to show more info
+ use "hg -v help multirevs" to show the global options
$ hg multirevs
hg multirevs: invalid arguments
--- a/tests/test-help.t Thu Oct 18 23:55:15 2012 -0500
+++ b/tests/test-help.t Thu Oct 18 10:31:15 2012 +0900
@@ -279,7 +279,7 @@
[+] marked option can be specified multiple times
- use "hg -v help add" to show more info
+ use "hg -v help add" to show more complete help and the global options
Verbose help for add
@@ -397,7 +397,7 @@
Returns 0 on success, 1 if errors are encountered.
- use "hg -v help verify" to show more info
+ use "hg -v help verify" to show the global options
$ hg help diff
hg diff [OPTION]... ([-c REV] | [-r REV1 [-r REV2]]) [FILE]...
@@ -450,7 +450,7 @@
[+] marked option can be specified multiple times
- use "hg -v help diff" to show more info
+ use "hg -v help diff" to show more complete help and the global options
$ hg help status
hg status [OPTION]... [FILE]...
@@ -513,7 +513,7 @@
[+] marked option can be specified multiple times
- use "hg -v help status" to show more info
+ use "hg -v help status" to show more complete help and the global options
$ hg -q help status
hg status [OPTION]... [FILE]...
@@ -599,7 +599,7 @@
(no help text available)
- use "hg -v help nohelp" to show more info
+ use "hg -v help nohelp" to show the global options
$ hg help -k nohelp
Commands:
@@ -805,6 +805,75 @@
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
--- a/tests/test-mq-qrefresh-interactive.t Thu Oct 18 23:55:15 2012 -0500
+++ b/tests/test-mq-qrefresh-interactive.t Thu Oct 18 10:31:15 2012 +0900
@@ -46,7 +46,7 @@
[+] marked option can be specified multiple times
- use "hg -v help qrefresh" to show more info
+ use "hg -v help qrefresh" to show the global options
help qrefresh (record)
@@ -91,7 +91,7 @@
[+] marked option can be specified multiple times
- use "hg -v help qrefresh" to show more info
+ use "hg -v help qrefresh" to show the global options
$ hg init a
$ cd a
--- a/tests/test-qrecord.t Thu Oct 18 23:55:15 2012 -0500
+++ b/tests/test-qrecord.t Thu Oct 18 10:31:15 2012 +0900
@@ -74,7 +74,7 @@
[+] marked option can be specified multiple times
- use "hg -v help record" to show more info
+ use "hg -v help record" to show the global options
help (no mq, so no qrecord)
@@ -85,7 +85,7 @@
See "hg help qnew" & "hg help record" for more information and usage.
- use "hg -v help qrecord" to show more info
+ use "hg -v help qrecord" to show the global options
$ hg init a
@@ -117,7 +117,7 @@
See "hg help qnew" & "hg help record" for more information and usage.
- use "hg -v help qrecord" to show more info
+ use "hg -v help qrecord" to show the global options
help (mq present)
@@ -150,7 +150,7 @@
[+] marked option can be specified multiple times
- use "hg -v help qrecord" to show more info
+ use "hg -v help qrecord" to show the global options
$ cd a