# HG changeset patch # User FUJIWARA Katsunori # Date 2012-10-18 01:31:15 # Node ID b623e323c56177b5e781543d3df2ece1d474b414 # Parent 98347af645933e1e01323912c819a4b69653641b 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. diff --git a/mercurial/commands.py b/mercurial/commands.py --- a/mercurial/commands.py +++ b/mercurial/commands.py @@ -3265,8 +3265,12 @@ def help_(ui, name=None, unknowncmd=Fals 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 @@ def help_(ui, name=None, unknowncmd=Fals 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 @@ def help_(ui, name=None, unknowncmd=Fals 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 @@ def help_(ui, name=None, unknowncmd=Fals 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) diff --git a/mercurial/help.py b/mercurial/help.py --- a/mercurial/help.py +++ b/mercurial/help.py @@ -61,6 +61,11 @@ def optrst(options, verbose): 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. diff --git a/tests/test-convert.t b/tests/test-convert.t --- a/tests/test-convert.t +++ b/tests/test-convert.t @@ -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 diff --git a/tests/test-encoding-align.t b/tests/test-encoding-align.t --- a/tests/test-encoding-align.t +++ b/tests/test-encoding-align.t @@ -59,7 +59,7 @@ check alignment of option descriptions i \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 diff --git a/tests/test-encoding-textwrap.t b/tests/test-encoding-textwrap.t --- a/tests/test-encoding-textwrap.t +++ b/tests/test-encoding-textwrap.t @@ -67,7 +67,7 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 @@ define commands to display help text \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 .. diff --git a/tests/test-extdiff.t b/tests/test-extdiff.t --- a/tests/test-extdiff.t +++ b/tests/test-extdiff.t @@ -47,7 +47,7 @@ Should diff cloned directories: [+] 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 diff --git a/tests/test-extension.t b/tests/test-extension.t --- a/tests/test-extension.t +++ b/tests/test-extension.t @@ -269,7 +269,7 @@ Extension module help vs command help: [+] 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 @@ Test help topic with same name as extens 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 diff --git a/tests/test-help.t b/tests/test-help.t --- a/tests/test-help.t +++ b/tests/test-help.t @@ -279,7 +279,7 @@ Test short command list with verbose opt [+] 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 @@ Test command without options 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 @@ Test command without options [+] 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 @@ Test command without options [+] 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 @@ Test command with no help text (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 @@ Test keyword search help qclone clone main and patch repository at same time +Test omit indicating for help + + $ cat > addverboseitems.py < '''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 diff --git a/tests/test-mq-qrefresh-interactive.t b/tests/test-mq-qrefresh-interactive.t --- a/tests/test-mq-qrefresh-interactive.t +++ b/tests/test-mq-qrefresh-interactive.t @@ -46,7 +46,7 @@ help qrefresh (no record) [+] 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 @@ help qrefresh (record) [+] 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 diff --git a/tests/test-qrecord.t b/tests/test-qrecord.t --- a/tests/test-qrecord.t +++ b/tests/test-qrecord.t @@ -74,7 +74,7 @@ help record (record) [+] 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 @@ help (no mq, so no qrecord) 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 @@ help (bad mq) 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 @@ help (mq present) [+] 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