Improve trac-admin help display

[techtonik <techtonik@…>]

Help page is too long. Here is a minor patch that allows to filter help results and adds "help list" command.

> trac-admin help list
component
deploy
help
hotcopy
initenv
milestone
permission
priority
resolution
resync
severity
ticket
ticket_type
upgrade
version
wiki

> trac-admin help wiki
wiki list
        -- List wiki pages

wiki remove <page>
        -- Remove wiki page

wiki export <page> [file]
        -- Export wiki page to file or stdout

wiki import <page> [file]
        -- Import wiki page from file or stdin

wiki dump <directory>
        -- Export all wiki pages to files named by title

wiki load <directory>
        -- Import all wiki pages from directory

wiki upgrade
        -- Upgrade default wiki pages to current version

[Christian Boos]

Nice.

I think we should eventually move in the direction of the Mercurial help, which is even nicer.

You'd have:

$ trac-admin help
...
(full list of command with one-liner help)
...
wiki list     list wiki pages
wiki remove   remove wiki page
wiki export   export wiki page to file or stdout
wiki import   import wiki page from file or stdin
wiki dump     export all wiki pages to files named by title
wiki load     import all wiki pages from directory
wiki upgrade  upgrade default wiki pages to current version
...

If you specify trac-admin help wiki, you'd have something similar to what your list subcommand does (i.e. only showing one-liner help for the wiki subcommands).

And then, a more precise help will be given when the command is given in full:

$ trac-admin help wiki export
wiki export <page> [file]
   Export wiki page to file or stdout

   (put here extended help if needed)

This would give us the possibility to show the one-liner help in a more concise way, plus to have extended usage information.

[techtonik@…]

svn, mercurial, bzr - current version control systems all have more or less unified command-line interface. Some of them are even "overcommandlined" like bazaar. Perhaps we can tune Python's optparse for console help API.

I am not sure that extended usage is needed though. Unless help spans more than one page I would avoid having another command to type.

[Remy Blank]

I'll look at this within the work I do for #7770.

[Remy Blank]

An improved way of displaying help for trac-admin has been committed in [7681]. It implements the suggestion in comment:1.

• trac-admin <env> help shows a compact list of all commands, without their arguments.

• trac-admin <env> help <cmd> shows a less compact form for the commands in the given group, and includes the command arguments.

• trac-admin <env> help <cmd> <subcmd> shows a long form, for commands that have a detailed explanation. See for example initenv or milestone due as examples.

[Remy Blank]

#7789 has been closed as a duplicate.