[PATCH V3] help: indicate help omitting if help document is not fully displayed

[FUJIWARA Katsunori]

# HG changeset patch
# User FUJIWARA Katsunori <foozy at lares.dti.ne.jp>
# Date 1342098028 -32400
# Node ID e7d520c785bd5bd2709515009a88c061797a971e
# Parent  2e13c1bd34dc6afda8fc7cfa22a8cd658276724f
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" by their experience on "hg help
-v" for some commands not containing verbose containers in their help
document.

Omitted help document is never seen by such users, and this may cause
wrong or insufficient understanding about Mercurial.

This patch indicates help omitting, if help document is not fully
displayed. This allows users to know whether there is any omitted
information or not exactly, and can trigger "hg help -v" invocation by
users.

diff -r 2e13c1bd34dc -r e7d520c785bd mercurial/commands.py
--- a/mercurial/commands.py	Wed Jul 04 17:29:49 2012 +0200
+++ b/mercurial/commands.py	Thu Jul 12 22:00:28 2012 +0900
@@ -3184,6 +3184,8 @@
         except KeyError:
             pass
 
+        help.indicateomitted(rst, name, ui.verbose)
+
         # options
         if not ui.quiet and entry[1]:
             rst.append('\n%s\n\n' % _("options:"))
@@ -3302,6 +3304,8 @@
         if util.safehasattr(doc, '__call__'):
             rst += ["    %s\n" % l for l in doc().splitlines()]
 
+        help.indicateomitted(rst, name, ui.verbose)
+
         try:
             cmdutil.findcmd(name, table)
             rst.append(_('\nuse "hg help -c %s" to see help for '
@@ -3329,6 +3333,8 @@
             rst.extend(tail.splitlines(True))
             rst.append('\n')
 
+        help.indicateomitted(rst, name, ui.verbose)
+
         if mod:
             try:
                 ct = mod.cmdtable
@@ -3392,7 +3398,11 @@
         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')
+        formatted, pruned = minirst.format(text, textwidth, keep=keep)
     ui.write(formatted)
 
 
diff -r 2e13c1bd34dc -r e7d520c785bd mercurial/help.py
--- a/mercurial/help.py	Wed Jul 04 17:29:49 2012 +0200
+++ b/mercurial/help.py	Thu Jul 12 22:00:28 2012 +0900
@@ -61,6 +61,13 @@
 
     return ''.join(rst)
 
+def indicateomitted(rst, name, verbose):
+    if not verbose:
+        # may be omitted
+        msg = _("(detailed description is omitted."
+                " use :hg:`help -v %s` to show details.)") % name
+        rst.append('\n\n.. container:: omitted\n\n    %s\n\n' % msg)
+
 def topicmatch(kw):
     """Return help topics matching kw.
 
diff -r 2e13c1bd34dc -r e7d520c785bd tests/test-help.t
--- a/tests/test-help.t	Wed Jul 04 17:29:49 2012 +0200
+++ b/tests/test-help.t	Thu Jul 12 22:00:28 2012 +0900
@@ -270,6 +270,8 @@
   
       Returns 0 if all files are successfully added.
   
+  (detailed description is omitted. use "hg help -v add" to show details.)
+  
   options:
   
    -I --include PATTERN [+] include names matching the given patterns
@@ -427,6 +429,8 @@
   
       Returns 0 on success.
   
+  (detailed description is omitted. use "hg help -v diff" to show details.)
+  
   options:
   
    -r --rev REV [+]         revision
@@ -489,6 +493,8 @@
   
       Returns 0 on success.
   
+  (detailed description is omitted. use "hg help -v status" to show details.)
+  
   options:
   
    -A --all                 show status of all files
@@ -802,3 +808,73 @@
   
    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)
+  
+  (detailed description is omitted. use "hg help -v addverboseitems" to show
+  details.)
+  
+  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)
+  
+  (detailed description is omitted. use "hg help -v topic-containing-verbose" to
+  show details.)
+  $ 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)