[PATCH] 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 1342015589 -32400
# Node ID c9dc22b313bf3ed8d8f81709568cf31230b1b8db
# 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 c9dc22b313bf mercurial/commands.py
--- a/mercurial/commands.py	Wed Jul 04 17:29:49 2012 +0200
+++ b/mercurial/commands.py	Wed Jul 11 23:06:29 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
diff -r 2e13c1bd34dc -r c9dc22b313bf mercurial/help.py
--- a/mercurial/help.py	Wed Jul 04 17:29:49 2012 +0200
+++ b/mercurial/help.py	Wed Jul 11 23:06:29 2012 +0900
@@ -61,6 +61,15 @@
 
     return ''.join(rst)
 
+def indicateomitted(rst, name, verbose):
+    if not verbose:
+        for text in rst:
+            if '.. container:: verbose' in text:
+                msg = _("(detailed description is omitted."
+                        " use :hg:`help -v %s` to show detail.)") % name
+                rst.append('\n%s\n\n' % msg)
+                return
+
 def topicmatch(kw):
     """Return help topics matching kw.
 
diff -r 2e13c1bd34dc -r c9dc22b313bf tests/test-help.t
--- a/tests/test-help.t	Wed Jul 04 17:29:49 2012 +0200
+++ b/tests/test-help.t	Wed Jul 11 23:06:29 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 detail.)
+  
   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 detail.)
+  
   options:
   
    -r --rev REV [+]         revision
@@ -489,6 +493,8 @@
   
       Returns 0 on success.
   
+  (detailed description is omitted. use "hg help -v status" to show detail.)
+  
   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
+  detail.)
+  
+  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 detail.)
+  $ 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)