You can already have deeply nested subcommands in docopt, take this example: https://github.com/docopt/docopt/blob/master/examples/git_ex...

Making possible several help-screens for different commands is on it's way. The only stopper—deciding on API: https://github.com/docopt/docopt/issues/17

Ah, that's great!

But I'd strongly vote for making it possible to annotate multiple functions and merging their respective doc-strings smartly.

I don't think you'd want to express the entire syntax-tree of a reasonably complex program (e.g. 'git') in a single doc-string. Not only would that turn into a mess, but you'd also lose modularity. I.e. subcommands often need to be dynamically generated (e.g. depending on loaded modules) and not all subcommands may be available at all times.

I'm also a fan of idea of using function-docstrings for separate subcommand help-screens. Problems: (1) exact API, (2) how to do that in non-python implementations. You (and everyone) is very welcome to suggest APIs for that in issues: https://github.com/docopt/docopt/issues

That exactly what [docopt](http://docopt.org/) is—DSL that allows implement almost any interface in one line (having formal interface description).

ahh, cool. suppose I should have read past the rules

It should be easy to port it - docopt is only 366 LOC itself.

wow, great! what is your scripting language?

I use Lua (http://www.lua.org) for personal projects.

I know a tiny bit of Lua. Write me halst@ya.ru or skype "halst." we can discuss your Lua port.