Improved help

I have been doing some thinking (out of code looking). So for now, just sharing a few thoughts, self-questions, etc.

I like the idea of the sections and how that will help for a possible endless growing list of commands. I don't think a command and a section should share names though. I think those has to be specifically forbidden (but some kind of check in drush).

What happens now if somebody declares a conflicting command?

I also think tried to think of how others strong command line tools work with this (cvs, svn, etc.), and although some similarity, they don't have that much commands.

cvs, on its own, gives a very standard simple help page when run on without any parameters, only telling you how to request more help, so that's probably in the line of the suggestion on this issue.

I have the following thought, which is just that, not sure if it's any better of this and I can expect some kind of big change within the code, but.. what if sections are commands as well, that requires sub commands?

drush sql or drush help sql would give help for the sql command, and the sql command requires subcommands (along with their options). So a sub command would be drush sql sync

Is this just too much?

no, I was thinking actually of a sync subcommand of sql, so only "drush sql sync", not "drush sql sql-sync"

I am not sure what the features command do, but say it lists features,

it would have to be something like:

"drush features list" rather than "drush features features", only standing in my way of thinking.

Now you mentioned it, I remeber that drush sql sync existed, and it seemed natural then.

I read a bit through the namespace issue that moved forward the namespacing of commands back then, and that made sense because "sql sync" was one command. But if you have subcommands, or sections/commands, "drush sql sync" seems a lot more appropriate now. It may seem like a step back, I know, but "drush sql sql-sync" is too redundant.

I see, well, ok. And knowing my thinking was way off only help, going back to drush sql sync (but now considering sql as a commend and sync as a subcommand), is something completely out of the question here? any thoughts on that. I know it's probably is, but now that I got to think of it...

We also have topics now. In general, I think there is not much to do on this issue.

Several times it has raised that the help page was getting bloated. This issue could fix this. Here's a proposal:

Show a general message on how to obtain more help and a list of available commandfiles:

drush
drush help

Show help on commands within a commandfile:

drush help commands core
drush help commands features

Show help on a command:

drush help command watchdog-show
drush help command features

/* and for compatible with current implementation */
drush help watchdog-show
drush help features

Perhaps with dashes: help-commands and help-command

I prefer that way rather than drush help features features discussed above.

I'm not too happy about the length of the help page but I'm hesitant to remove anything :). I think that requiring a grouping in order to view command list is frustrating. The whole reason you are doing the list is because you can't remember if it is site-aliases or core-sa or pm-aliases or whatever. Nobody likes to hunt for this stuff.

I actually tinkered with moving the Global options off the Help page. We would add a message informing user how to learn more about them. But often you need --url just to get anything working so maybe we have to list the most common on the main page still.

I eventually did move rarely used global options into a topic so the help page is a bit slimmer now. I'm currently not to inclined to pursue this but am open to discussion.

I like it. I'd say we can do without the new --list option and just document the behavior of --filter without a value. This parallels --result-file. After that, lets commit.