Page MenuHomePhabricator

help: register the 'gpg' command category and give it a description
ClosedPublic

Authored by Sietse on Apr 28 2019, 5:17 PM.

Details

Summary

help.py expects extensions to register their command category in the
CATEGORY_ORDER and CATEGORY_NAMES variables. Once gendoc.py orders
commands by category, in the next patch, it'll assume this registration
(and raise an exception on encountering any unregistered categories).
Luckily, gpg is the only bundled extension with an unregistered custom
category, so let's fix it.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

Sietse created this revision.Apr 28 2019, 5:17 PM
martinvonz accepted this revision.May 3 2019, 12:35 PM
martinvonz added a subscriber: martinvonz.
martinvonz added inline comments.
hgext/gpg.py
56

This feels a little too specific, but we can come up with a better category for it if we get other related commands.

This revision is now accepted and ready to land.May 3 2019, 12:35 PM

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?

This revision was automatically updated to reflect the committed changes.

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.

hgext/gpg.py
56

"Security"?

Sietse added a comment.EditedMay 7 2019, 12:40 PM

[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:

[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.

Sietse added a comment.May 7 2019, 1:32 PM

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.