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.

mercurial/commands.py

@@ -3265,8 +3265,12 b' 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 b' 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 b' 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 b' 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)
 
 

mercurial/help.py

@@ -61,6 +61,11 b' 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.
 

tests/test-convert.t

@@ -261,7 +261,7 b''
       --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

tests/test-encoding-align.t

@@ -59,7 +59,7 b' 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

tests/test-encoding-textwrap.t

@@ -67,7 +67,7 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 ..

tests/test-extdiff.t

@@ -47,7 +47,7 b' 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
 

tests/test-extension.t

@@ -269,7 +269,7 b' 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 b' 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

tests/test-help.t

@@ -279,7 +279,7 b' 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 b' 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 b' 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 b' 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 b' 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 b' Test keyword search help'
   
    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

tests/test-mq-qrefresh-interactive.t

@@ -46,7 +46,7 b' 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 b' 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

tests/test-qrecord.t

@@ -74,7 +74,7 b' 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 b' 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 b' 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 b' 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