D6324: help: register the 'gpg' command category and give it a description
Sietse added a comment. **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. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D6324 To: Sietse, #hg-reviewers, martinvonz Cc: rdamazio, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D6324: help: register the 'gpg' command category and give it a description
martinvonz added a comment. In https://phab.mercurial-scm.org/D6324#92372, @Sietse wrote: > In https://phab.mercurial-scm.org/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 https://phab.mercurial-scm.org/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. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D6324 To: Sietse, #hg-reviewers, martinvonz Cc: rdamazio, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D6324: help: register the 'gpg' command category and give it a description
Sietse added a comment. In https://phab.mercurial-scm.org/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? > ! In https://phab.mercurial-scm.org/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. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D6324 To: Sietse, #hg-reviewers, martinvonz Cc: rdamazio, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D6324: help: register the 'gpg' command category and give it a description
rdamazio added a comment. In https://phab.mercurial-scm.org/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. INLINE COMMENTS > martinvonz wrote in 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. "Security"? REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D6324 To: Sietse, #hg-reviewers, martinvonz Cc: rdamazio, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D6324: help: register the 'gpg' command category and give it a description
martinvonz added a subscriber: rdamazio. martinvonz added a comment. 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? REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D6324 To: Sietse, #hg-reviewers, martinvonz Cc: rdamazio, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D6324: help: register the 'gpg' command category and give it a description
This revision was automatically updated to reflect the committed changes. Closed by commit rHGade02721d3fa: help: register the gpg command category and give it a description (authored by Sietse, committed by ). REPOSITORY rHG Mercurial CHANGES SINCE LAST UPDATE https://phab.mercurial-scm.org/D6324?vs=14957=14993 REVISION DETAIL https://phab.mercurial-scm.org/D6324 AFFECTED FILES hgext/gpg.py CHANGE DETAILS diff --git a/hgext/gpg.py b/hgext/gpg.py --- a/hgext/gpg.py +++ b/hgext/gpg.py @@ -49,6 +49,11 @@ # Custom help category _HELP_CATEGORY = 'gpg' +help.CATEGORY_ORDER.insert( +help.CATEGORY_ORDER.index(registrar.command.CATEGORY_HELP), +_HELP_CATEGORY +) +help.CATEGORY_NAMES[_HELP_CATEGORY] = 'Signing changes (GPG)' class gpg(object): def __init__(self, path, key=None): To: Sietse, #hg-reviewers, martinvonz Cc: rdamazio, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D6324: help: register the 'gpg' command category and give it a description
martinvonz accepted this revision. martinvonz added inline comments. This revision is now accepted and ready to land. INLINE COMMENTS > gpg.py:56 > +) > +help.CATEGORY_NAMES[_HELP_CATEGORY] = 'Signing changes (GPG)' > This feels a little too specific, but we can come up with a better category for it if we get other related commands. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D6324 To: Sietse, #hg-reviewers, martinvonz Cc: martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D6324: help: register the 'gpg' command category and give it a description
Sietse created this revision. Herald added a subscriber: mercurial-devel. Herald added a reviewer: hg-reviewers. REVISION 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. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D6324 AFFECTED FILES hgext/gpg.py CHANGE DETAILS diff --git a/hgext/gpg.py b/hgext/gpg.py --- a/hgext/gpg.py +++ b/hgext/gpg.py @@ -49,6 +49,11 @@ # Custom help category _HELP_CATEGORY = 'gpg' +help.CATEGORY_ORDER.insert( +help.CATEGORY_ORDER.index(registrar.command.CATEGORY_HELP), +_HELP_CATEGORY +) +help.CATEGORY_NAMES[_HELP_CATEGORY] = 'Signing changes (GPG)' class gpg(object): def __init__(self, path, key=None): To: Sietse, #hg-reviewers Cc: mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
