[PATCH] help: 'hg help' supports subtopics (issue2804)

Yun Lee yun.lee.bj at gmail.com
Wed May 11 11:06:59 CDT 2011


# HG changeset patch
# User Yun Lee <yun.lee.bj at gmail.com>
# Date 1305126936 -28800
# Branch stable
# Node ID 42b999b362e67500d4c6c57f5c09f6641ce9872b
# Parent  89e7d35e0ef09ed3d9c9f6bbd2803c9c8639fcca
help: 'hg help' supports subtopics (issue2804)

diff -r 89e7d35e0ef0 -r 42b999b362e6 doc/gendoc.py
--- a/doc/gendoc.py	Sun May 01 13:07:00 2011 +0200
+++ b/doc/gendoc.py	Wed May 11 23:15:36 2011 +0800
@@ -86,7 +86,7 @@
     commandprinter(ui, table, subsection)
 
     # print topics
-    for names, sec, doc in helptable:
+    for names, sec, doc, subtopics in helptable:
         for name in names:
             ui.write(".. _%s:\n" % name)
         ui.write("\n")
diff -r 89e7d35e0ef0 -r 42b999b362e6 mercurial/commands.py
--- a/mercurial/commands.py	Sun May 01 13:07:00 2011 +0200
+++ b/mercurial/commands.py	Wed May 11 23:15:36 2011 +0800
@@ -2083,12 +2083,25 @@
             addglobalopts(True)
 
     def helptopic(name):
-        for names, header, doc in help.helptable:
-            if name in names:
+        topic, subtopic = (name, None)
+                
+        if '.' in name:
+            topic, subtopic = name.split('.')
+        
+        for topics, header, doc, subtopics in help.helptable:
+            if topic in topics:
                 break
+            print topics
         else:
             raise error.UnknownCommand(name)
 
+        if subtopic:            
+            for names, header, doc in subtopics:
+                if subtopic in names:
+                    break
+            else:
+                raise error.UnknownCommand(name)
+
         # description
         if not doc:
             doc = _("(no help text available)")
@@ -2097,6 +2110,13 @@
 
         ui.write("%s\n\n" % header)
         ui.write("%s\n" % minirst.format(doc, textwidth, indent=4))
+        
+        if not subtopic and subtopics:
+            ui.write("\n\nsubtopics:\n\n")
+            
+            for subtopicitem in subtopics:
+                ui.write('  %-10s : %s\n' % (subtopicitem[0][0], subtopicitem[1]))
+        
 
     def helpext(name):
         try:
@@ -2218,7 +2238,7 @@
     if not name:
         ui.write(_("\nadditional help topics:\n\n"))
         topics = []
-        for names, header, doc in help.helptable:
+        for names, header, doc, subtopics in help.helptable:
             topics.append((sorted(names, key=len, reverse=True)[0], header))
         topics_len = max([len(s[0]) for s in topics])
         for t, desc in topics:
diff -r 89e7d35e0ef0 -r 42b999b362e6 mercurial/help.py
--- a/mercurial/help.py	Sun May 01 13:07:00 2011 +0200
+++ b/mercurial/help.py	Wed May 11 23:15:36 2011 +0800
@@ -86,26 +86,53 @@
 
     return loader
 
+def loadsubdoc(topic, subtopic):
+    def loader():
+        if hasattr(sys, 'frozen'):
+            module = sys.executable
+        else:
+            module = __file__
+        base = os.path.dirname(module)
+
+        for dir in ('', '..', '.'):
+            docdir = os.path.join(base, dir, 'help')
+            if os.path.isdir(docdir):
+                break
+
+        path = os.path.join(docdir, topic, subtopic + ".txt")
+        
+        doc = gettext(open(path).read())
+        for rewriter in helphooks.get(topic, []):
+            doc = rewriter(topic, doc)
+        return doc
+
+    return loader
+
+
 helptable = [
-    (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
-    (["dates"], _("Date Formats"), loaddoc('dates')),
-    (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
+    (["config", "hgrc"], _("Configuration Files"), loaddoc('config')
+     , [(["alias"], _("Defines command aliases"), loadsubdoc('config', 'alias')),
+        (["auth"], _("Defines  Authentication credentials"), loadsubdoc('config', 'auth')),
+        (["defaults"], _("Defines command defaults"), loadsubdoc('config', 'defaults')),
+        ]),
+    (["dates"], _("Date Formats"), loaddoc('dates'), []),
+    (["patterns"], _("File Name Patterns"), loaddoc('patterns'), []),
     (['environment', 'env'], _('Environment Variables'),
-     loaddoc('environment')),
+     loaddoc('environment'), []),
     (['revs', 'revisions'], _('Specifying Single Revisions'),
-     loaddoc('revisions')),
+     loaddoc('revisions'), []),
     (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'),
-     loaddoc('multirevs')),
-    (['revset', 'revsets'], _("Specifying Revision Sets"), loaddoc('revsets')),
-    (['diffs'], _('Diff Formats'), loaddoc('diffs')),
-    (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools')),
+     loaddoc('multirevs'), []),
+    (['revset', 'revsets'], _("Specifying Revision Sets"), loaddoc('revsets'), []),
+    (['diffs'], _('Diff Formats'), loaddoc('diffs'), []),
+    (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools'), []),
     (['templating', 'templates'], _('Template Usage'),
-     loaddoc('templates')),
-    (['urls'], _('URL Paths'), loaddoc('urls')),
-    (["extensions"], _("Using additional features"), extshelp),
-    (["subrepo", "subrepos"], _("Subrepositories"), loaddoc('subrepos')),
-    (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
-    (["glossary"], _("Glossary"), loaddoc('glossary')),
+     loaddoc('templates'), []),
+    (['urls'], _('URL Paths'), loaddoc('urls'), []),
+    (["extensions"], _("Using additional features"), extshelp, []),
+    (["subrepo", "subrepos"], _("Subrepositories"), loaddoc('subrepos'), []),
+    (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb'), []),
+    (["glossary"], _("Glossary"), loaddoc('glossary'), []),
 ]
 
 # Map topics to lists of callable taking the current topic help and
diff -r 89e7d35e0ef0 -r 42b999b362e6 mercurial/help/config/alias.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/config/alias.txt	Wed May 11 23:15:36 2011 +0800
@@ -0,0 +1,19 @@
+Aliases allow you to define your own commands in terms of other
+commands (or aliases), optionally including arguments.
+
+Alias definitions consist of lines of the form::
+
+    <alias> = <command> [<argument]...
+
+For example, this definition::
+
+    latest = log --limit 5
+
+creates a new command ``latest`` that shows only the five most recent
+changesets. You can define subsequent aliases using earlier ones::
+
+    stable5 = latest -b stable
+
+.. note:: It is possible to create aliases with the same names as
+   existing commands, which will then override the original
+   definitions. This is almost always a bad idea!
diff -r 89e7d35e0ef0 -r 42b999b362e6 mercurial/help/config/auth.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/config/auth.txt	Wed May 11 23:15:36 2011 +0800
@@ -0,0 +1,55 @@
+Authentication credentials for HTTP authentication. This section
+allows you to store usernames and passwords for use when logging
+*into* HTTP servers. See the web_ configuration section if you want to
+configure *who* can login to your HTTP server.
+
+Each line has the following format::
+
+    <name>.<argument> = <value>
+
+where ``<name>`` is used to group arguments into authentication
+entries. Example::
+
+    foo.prefix = hg.intevation.org/mercurial
+    foo.username = foo
+    foo.password = bar
+    foo.schemes = http https
+
+    bar.prefix = secure.example.org
+    bar.key = path/to/file.key
+    bar.cert = path/to/file.cert
+    bar.schemes = https
+
+Supported arguments:
+
+``prefix``
+    Either ``*`` or a URI prefix with or without the scheme part.
+    The authentication entry with the longest matching prefix is used
+    (where ``*`` matches everything and counts as a match of length
+    1). If the prefix doesn't include a scheme, the match is performed
+    against the URI with its scheme stripped as well, and the schemes
+    argument, q.v., is then subsequently consulted.
+``username``
+    Optional. Username to authenticate with. If not given, and the
+    remote site requires basic or digest authentication, the user will
+    be prompted for it. Environment variables are expanded in the
+    username letting you do ``foo.username = $USER``.
+``password``
+    Optional. Password to authenticate with. If not given, and the
+    remote site requires basic or digest authentication, the user
+    will be prompted for it.
+``key``
+    Optional. PEM encoded client certificate key file. Environment
+    variables are expanded in the filename.
+``cert``
+    Optional. PEM encoded client certificate chain file. Environment
+    variables are expanded in the filename.
+``schemes``
+    Optional. Space separated list of URI schemes to use this
+    authentication entry with. Only used if the prefix doesn't include
+    a scheme. Supported schemes are http and https. They will match
+    static-http and static-https respectively, as well.
+    Default: https.
+
+If no suitable authentication entry is found, the user is prompted
+for credentials as usual if required by the remote.
\ No newline at end of file
diff -r 89e7d35e0ef0 -r 42b999b362e6 mercurial/help/config/defaults.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/config/defaults.txt	Wed May 11 23:15:36 2011 +0800
@@ -0,0 +1,15 @@
+(defaults are deprecated. Don't use them. Use aliases instead)
+
+Use the ``[defaults]`` section to define command defaults, i.e. the
+default options/arguments to pass to the specified commands.
+
+The following example makes :hg:`log` run in verbose mode, and
+:hg:`status` show only the modified files, by default::
+
+  [defaults]
+  log = -v
+  status = -m
+
+The actual commands, instead of their aliases, must be used when
+defining command defaults. The command defaults will also be applied
+to the aliases of the commands defined.


More information about the Mercurial-devel mailing list