This doesn't actually seem to work for making it appear in hg help. @rdamazio (who added the categories stuff), have you thought about a way of letting extensions add categories?

In D6324#92158, @martinvonz wrote:

This doesn't actually seem to work for making it appear in hg help. @rdamazio (who added the categories stuff), have you thought about a way of letting extensions add categories?

I did, this was supposed to be it - maybe I missed something or it broke somehow? :/
I need to migrate Google's extension out of the internal version of help (now that I've upstreamed the help changes), I'll definitely need to mess with categories for that, too.

In D6324#92158, @martinvonz wrote:

[registering the gpg command category] doesn't actually seem to work for making it appear in hg help.

Perhaps, instead of doing work to group extension commands by category, the commands should be grouped under the extension. Nearly all my (enabled and disabled) extensions have 5 commands or less; only evolve and mq have more (17 + 7 debug, and 26, respectively). (Almost) None of them use any command categories. Only GPG does, but that uses the same category for all its commands.

The only reason that the help pages currently group extension functions by command category is that gendoc.py currently uses the same commandprinter function first to print the main command table, and then once per extension to render the extension's commands. I would be willing to separate that functionality so that extensions could have their own rendering function, which ignores categories (or ignores them if there is only one). Shall I take that on?

! In D6324#92354, @rdamazio wrote:
I need to migrate Google's extension out of the internal version of help (now that I've upstreamed the help changes), I'll definitely need to mess with categories for that, too.

Does Google's extension have a lot of commands? Do they need categories?

In D6324#92372, @Sietse wrote:

In D6324#92158, @martinvonz wrote:

[registering the gpg command category] doesn't actually seem to work for making it appear in hg help.

Perhaps, instead of doing work to group extension commands by category, the commands should be grouped under the extension. Nearly all my (enabled and disabled) extensions have 5 commands or less; only evolve and mq have more (17 + 7 debug, and 26, respectively). (Almost) None of them use any command categories. Only GPG does, but that uses the same category for all its commands.
The only reason that the help pages currently group extension functions by command category is that gendoc.py currently uses the same commandprinter function first to print the main command table, and then once per extension to render the extension's commands. I would be willing to separate that functionality so that extensions could have their own rendering function, which ignores categories. Shall I take that on?

I think it makes sense for extensions to be able to add commands to existing categories (e.g. evolve's next/prev commands seem like they should be in the same category as update), so I don't want to lose that (as I think you suggested).

! In D6324#92354, @rdamazio wrote:
I need to migrate Google's extension out of the internal version of help (now that I've upstreamed the help changes), I'll definitely need to mess with categories for that, too.

NB: I was wrong about extensions not using helpcategories. I checked something different than I thought I had. They do add categories to their commands.

Currently (i.e. after this patch stack, because it has been accepted) the hierarchy (in the man page / HTML help) is like so (ignoring the fact that man pages flatten the last few levels of the hierarchy due to less levels). As you can see, even when a command has an existing category the command will be displayed in that category nested underneath the extension, rather than merged into the existing command category. As long as that arrangement is used, I'd say it reduces the value of re-using existing command categories.

• COMMANDS
  • Repository creation
    • • clone
      • init
    • Next category ...
      • more commands ...
• EXTENSIONS
  • absorb
    • Commands
      • Change creation
        • absorb
  • acl
    • Commands
      • more categories ...
        • more commands ...
  • more extensions...
    • Commands
      • more categories...
        • more commands...

Perhaps something like this would be better. It would group by category; extensions could add commands to existing categories; commands from extensions would be marked as such.

• COMMANDS
  • Working directory management
    • status: show changed files in the working directory
    • summary: summarize working directory state
    • update: update working directory (or switch revisions)
    • next (evolve): update to child commit, evolving history if needed
    • prev (evolve): update to parent commit

Is this still the right medium for this discussion? I'm naturally interested because I read the code recently, but I don't want to overwhelm you with bikeshedding.