help: assigning topic categories

Differential Revision: https://phab.mercurial-scm.org/D5068

doc/gendoc.py

@@ -138,13 +138,14 b' def showdoc(ui):'
 
 def showtopic(ui, topic):
     extrahelptable = [
-        (["common"], '', loaddoc('common')),
-        (["hg.1"], '', loaddoc('hg.1')),
-        (["hg-ssh.8"], '', loaddoc('hg-ssh.8')),
-        (["hgignore.5"], '', loaddoc('hgignore.5')),
-        (["hgrc.5"], '', loaddoc('hgrc.5')),
-        (["hgignore.5.gendoc"], '', loaddoc('hgignore')),
-        (["hgrc.5.gendoc"], '', loaddoc('config')),
+        (["common"], '', loaddoc('common'), help.TOPIC_CATEGORY_MISC),
+        (["hg.1"], '', loaddoc('hg.1'), help.TOPIC_CATEGORY_CONFIG),
+        (["hg-ssh.8"], '', loaddoc('hg-ssh.8'), help.TOPIC_CATEGORY_CONFIG),
+        (["hgignore.5"], '', loaddoc('hgignore.5'), help.TOPIC_CATEGORY_CONFIG),
+        (["hgrc.5"], '', loaddoc('hgrc.5'), help.TOPIC_CATEGORY_CONFIG),
+        (["hgignore.5.gendoc"], '', loaddoc('hgignore'),
+         help.TOPIC_CATEGORY_CONFIG),
+        (["hgrc.5.gendoc"], '', loaddoc('config'), help.TOPIC_CATEGORY_CONFIG),
     ]
     helpprinter(ui, helptable + extrahelptable, None, include=[topic])
 

mercurial/help.py

@@ -89,6 +89,11 b' CATEGORY_NAMES = {'
 }
 
 # Topic categories.
+TOPIC_CATEGORY_IDS = 'ids'
+TOPIC_CATEGORY_OUTPUT = 'output'
+TOPIC_CATEGORY_CONFIG = 'config'
+TOPIC_CATEGORY_CONCEPTS = 'concepts'
+TOPIC_CATEGORY_MISC = 'misc'
 TOPIC_CATEGORY_NONE = 'none'
 
 # The order in which topic categories will be displayed.
@@ -96,11 +101,22 b" TOPIC_CATEGORY_NONE = 'none'"
 # after/before the appropriate item, rather than replacing the list or
 # assuming absolute positions.
 TOPIC_CATEGORY_ORDER = [
+    TOPIC_CATEGORY_IDS,
+    TOPIC_CATEGORY_OUTPUT,
+    TOPIC_CATEGORY_CONFIG,
+    TOPIC_CATEGORY_CONCEPTS,
+    TOPIC_CATEGORY_MISC,
     TOPIC_CATEGORY_NONE,
 ]
 
 # Human-readable topic category names. These are translated.
 TOPIC_CATEGORY_NAMES = {
+    TOPIC_CATEGORY_IDS: 'Mercurial identifiers',
+    TOPIC_CATEGORY_OUTPUT: 'Mercurial output',
+    TOPIC_CATEGORY_CONFIG: 'Mercurial configuration',
+    TOPIC_CATEGORY_CONCEPTS: 'Concepts',
+    TOPIC_CATEGORY_MISC: 'Miscellaneous',
+    TOPIC_CATEGORY_NONE: 'Uncategorized topics',
     TOPIC_CATEGORY_NONE: 'Uncategorized topics',
 }
 
@@ -293,36 +309,47 b' def internalshelp(ui):'
     return ''.join(lines)
 
 helptable = sorted([
-    (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')),
-    (['color'], _("Colorizing Outputs"), loaddoc('color')),
-    (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
-    (['deprecated'], _("Deprecated Features"), loaddoc('deprecated')),
-    (["dates"], _("Date Formats"), loaddoc('dates')),
-    (["flags"], _("Command-line flags"), loaddoc('flags')),
-    (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
+    (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec'),
+     TOPIC_CATEGORY_CONCEPTS),
+    (['color'], _("Colorizing Outputs"), loaddoc('color'),
+     TOPIC_CATEGORY_OUTPUT),
+    (["config", "hgrc"], _("Configuration Files"), loaddoc('config'),
+     TOPIC_CATEGORY_CONFIG),
+    (['deprecated'], _("Deprecated Features"), loaddoc('deprecated'),
+     TOPIC_CATEGORY_MISC),
+    (["dates"], _("Date Formats"), loaddoc('dates'), TOPIC_CATEGORY_OUTPUT),
+    (["flags"], _("Command-line flags"), loaddoc('flags'),
+     TOPIC_CATEGORY_CONFIG),
+    (["patterns"], _("File Name Patterns"), loaddoc('patterns'),
+     TOPIC_CATEGORY_IDS),
     (['environment', 'env'], _('Environment Variables'),
-     loaddoc('environment')),
+     loaddoc('environment'), TOPIC_CATEGORY_CONFIG),
     (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
-      _('Specifying Revisions'), loaddoc('revisions')),
-    (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')),
-    (['diffs'], _('Diff Formats'), loaddoc('diffs')),
+      _('Specifying Revisions'), loaddoc('revisions'), TOPIC_CATEGORY_IDS),
+    (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets'),
+     TOPIC_CATEGORY_IDS),
+    (['diffs'], _('Diff Formats'), loaddoc('diffs'), TOPIC_CATEGORY_OUTPUT),
     (['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),
-     loaddoc('merge-tools')),
+     loaddoc('merge-tools'), TOPIC_CATEGORY_CONFIG),
     (['templating', 'templates', 'template', 'style'], _('Template Usage'),
-     loaddoc('templates')),
-    (['urls'], _('URL Paths'), loaddoc('urls')),
-    (["extensions"], _("Using Additional Features"), extshelp),
-    (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')),
-    (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
-    (["glossary"], _("Glossary"), loaddoc('glossary')),
+     loaddoc('templates'), TOPIC_CATEGORY_OUTPUT),
+    (['urls'], _('URL Paths'), loaddoc('urls'), TOPIC_CATEGORY_IDS),
+    (["extensions"], _("Using Additional Features"), extshelp,
+     TOPIC_CATEGORY_CONFIG),
+    (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos'),
+     TOPIC_CATEGORY_CONCEPTS),
+    (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb'),
+     TOPIC_CATEGORY_CONFIG),
+    (["glossary"], _("Glossary"), loaddoc('glossary'), TOPIC_CATEGORY_CONCEPTS),
     (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
-     loaddoc('hgignore')),
-    (["phases"], _("Working with Phases"), loaddoc('phases')),
+     loaddoc('hgignore'), TOPIC_CATEGORY_IDS),
+    (["phases"], _("Working with Phases"), loaddoc('phases'),
+     TOPIC_CATEGORY_CONCEPTS),
     (['scripting'], _('Using Mercurial from scripts and automation'),
-     loaddoc('scripting')),
-    (['internals'], _("Technical implementation topics"),
-     internalshelp),
-    (['pager'], _("Pager Support"), loaddoc('pager')),
+     loaddoc('scripting'), TOPIC_CATEGORY_MISC),
+    (['internals'], _("Technical implementation topics"), internalshelp,
+     TOPIC_CATEGORY_MISC),
+    (['pager'], _("Pager Support"), loaddoc('pager'), TOPIC_CATEGORY_CONFIG),
 ])
 
 # Maps topics with sub-topics to a list of their sub-topics.

tests/test-globalopts.t

@@ -382,29 +382,43 b' Testing -h/--help:'
   
   additional help topics:
   
-   bundlespec    Bundle File Formats
+  Mercurial identifiers:
+  
+   filesets      Specifying File Sets
+   hgignore      Syntax for Mercurial Ignore Files
+   patterns      File Name Patterns
+   revisions     Specifying Revisions
+   urls          URL Paths
+  
+  Mercurial output:
+  
    color         Colorizing Outputs
+   dates         Date Formats
+   diffs         Diff Formats
+   templating    Template Usage
+  
+  Mercurial configuration:
+  
    config        Configuration Files
-   dates         Date Formats
-   deprecated    Deprecated Features
-   diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
-   filesets      Specifying File Sets
    flags         Command-line flags
-   glossary      Glossary
-   hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
-   internals     Technical implementation topics
    merge-tools   Merge Tools
    pager         Pager Support
-   patterns      File Name Patterns
+  
+  Concepts:
+  
+   bundlespec    Bundle File Formats
+   glossary      Glossary
    phases        Working with Phases
-   revisions     Specifying Revisions
+   subrepos      Subrepositories
+  
+  Miscellaneous:
+  
+   deprecated    Deprecated Features
+   internals     Technical implementation topics
    scripting     Using Mercurial from scripts and automation
-   subrepos      Subrepositories
-   templating    Template Usage
-   urls          URL Paths
   
   (use 'hg help -v' to show built-in aliases and global options)
 
@@ -498,29 +512,43 b' Testing -h/--help:'
   
   additional help topics:
   
-   bundlespec    Bundle File Formats
+  Mercurial identifiers:
+  
+   filesets      Specifying File Sets
+   hgignore      Syntax for Mercurial Ignore Files
+   patterns      File Name Patterns
+   revisions     Specifying Revisions
+   urls          URL Paths
+  
+  Mercurial output:
+  
    color         Colorizing Outputs
+   dates         Date Formats
+   diffs         Diff Formats
+   templating    Template Usage
+  
+  Mercurial configuration:
+  
    config        Configuration Files
-   dates         Date Formats
-   deprecated    Deprecated Features
-   diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
-   filesets      Specifying File Sets
    flags         Command-line flags
-   glossary      Glossary
-   hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
-   internals     Technical implementation topics
    merge-tools   Merge Tools
    pager         Pager Support
-   patterns      File Name Patterns
+  
+  Concepts:
+  
+   bundlespec    Bundle File Formats
+   glossary      Glossary
    phases        Working with Phases
-   revisions     Specifying Revisions
+   subrepos      Subrepositories
+  
+  Miscellaneous:
+  
+   deprecated    Deprecated Features
+   internals     Technical implementation topics
    scripting     Using Mercurial from scripts and automation
-   subrepos      Subrepositories
-   templating    Template Usage
-   urls          URL Paths
   
   (use 'hg help -v' to show built-in aliases and global options)
 

tests/test-help.t

@@ -138,29 +138,43 b' the extension is unknown.'
   
   additional help topics:
   
-   bundlespec    Bundle File Formats
+  Mercurial identifiers:
+  
+   filesets      Specifying File Sets
+   hgignore      Syntax for Mercurial Ignore Files
+   patterns      File Name Patterns
+   revisions     Specifying Revisions
+   urls          URL Paths
+  
+  Mercurial output:
+  
    color         Colorizing Outputs
+   dates         Date Formats
+   diffs         Diff Formats
+   templating    Template Usage
+  
+  Mercurial configuration:
+  
    config        Configuration Files
-   dates         Date Formats
-   deprecated    Deprecated Features
-   diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
-   filesets      Specifying File Sets
    flags         Command-line flags
-   glossary      Glossary
-   hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
-   internals     Technical implementation topics
    merge-tools   Merge Tools
    pager         Pager Support
-   patterns      File Name Patterns
+  
+  Concepts:
+  
+   bundlespec    Bundle File Formats
+   glossary      Glossary
    phases        Working with Phases
-   revisions     Specifying Revisions
+   subrepos      Subrepositories
+  
+  Miscellaneous:
+  
+   deprecated    Deprecated Features
+   internals     Technical implementation topics
    scripting     Using Mercurial from scripts and automation
-   subrepos      Subrepositories
-   templating    Template Usage
-   urls          URL Paths
   
   (use 'hg help -v' to show built-in aliases and global options)
 
@@ -250,29 +264,43 b' the extension is unknown.'
   
   additional help topics:
   
-   bundlespec    Bundle File Formats
+  Mercurial identifiers:
+  
+   filesets      Specifying File Sets
+   hgignore      Syntax for Mercurial Ignore Files
+   patterns      File Name Patterns
+   revisions     Specifying Revisions
+   urls          URL Paths
+  
+  Mercurial output:
+  
    color         Colorizing Outputs
+   dates         Date Formats
+   diffs         Diff Formats
+   templating    Template Usage
+  
+  Mercurial configuration:
+  
    config        Configuration Files
-   dates         Date Formats
-   deprecated    Deprecated Features
-   diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
-   filesets      Specifying File Sets
    flags         Command-line flags
-   glossary      Glossary
-   hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
-   internals     Technical implementation topics
    merge-tools   Merge Tools
    pager         Pager Support
-   patterns      File Name Patterns
+  
+  Concepts:
+  
+   bundlespec    Bundle File Formats
+   glossary      Glossary
    phases        Working with Phases
-   revisions     Specifying Revisions
+   subrepos      Subrepositories
+  
+  Miscellaneous:
+  
+   deprecated    Deprecated Features
+   internals     Technical implementation topics
    scripting     Using Mercurial from scripts and automation
-   subrepos      Subrepositories
-   templating    Template Usage
-   urls          URL Paths
 
 Test extension help:
   $ hg help extensions --config extensions.rebase= --config extensions.children=
@@ -963,29 +991,43 b' Test that default list of commands omits'
   
   additional help topics:
   
-   bundlespec    Bundle File Formats
+  Mercurial identifiers:
+  
+   filesets      Specifying File Sets
+   hgignore      Syntax for Mercurial Ignore Files
+   patterns      File Name Patterns
+   revisions     Specifying Revisions
+   urls          URL Paths
+  
+  Mercurial output:
+  
    color         Colorizing Outputs
+   dates         Date Formats
+   diffs         Diff Formats
+   templating    Template Usage
+  
+  Mercurial configuration:
+  
    config        Configuration Files
-   dates         Date Formats
-   deprecated    Deprecated Features
-   diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
-   filesets      Specifying File Sets
    flags         Command-line flags
-   glossary      Glossary
-   hgignore      Syntax for Mercurial Ignore Files
    hgweb         Configuring hgweb
-   internals     Technical implementation topics
    merge-tools   Merge Tools
    pager         Pager Support
-   patterns      File Name Patterns
+  
+  Concepts:
+  
+   bundlespec    Bundle File Formats
+   glossary      Glossary
    phases        Working with Phases
-   revisions     Specifying Revisions
+   subrepos      Subrepositories
+  
+  Miscellaneous:
+  
+   deprecated    Deprecated Features
+   internals     Technical implementation topics
    scripting     Using Mercurial from scripts and automation
-   subrepos      Subrepositories
-   templating    Template Usage
-   urls          URL Paths
   
   (use 'hg help -v' to show built-in aliases and global options)