question: how to use multiple Markdown definition files, one for each command?

[boneskull]

Thanks for replying in cli-interface to my previous question. Can you please explain how to use multiple Markdown definition files when configuring commands?

thanks,
Chris

[tmpfs]

You should check out the config example:

https://raw.github.com/freeformsystems/cli-command/master/ebin/subcommand/config.md
https://github.com/freeformsystems/cli-command/blob/master/ebin/subcommand/config

Which at some point will be migrated to middleware. Not the use of level 3 headings (### Configuration) to match the command with it's declared child options/commands.

Also note the loose regexp matching, such that the command has a key of conf however the heading is Configuration. You could be more explicit and declare the top-level command with a key-prefix but that is another topic I need to document.

Hope this helps, let me know if it is not clear.

[boneskull]

I'm not sure if this is quite what I'm getting at. I'll explain:

Ideally, I would like to execute ./config --help and see only:

• all top-level commands
• global options

Let's pretend command conf takes options and/or subcommands. Then I would like to execute ./config conf --help and see:

• subcommands unique to conf
• options unique to conf
• all global options

At the very least, it sounds like I want unique help configurations for each command--which is why I asked earlier about multiple Markdown files.

Accepting multiple commands at once would complicate this, since it may not be clear which help to show (./program foo bar baz --help shows help for command foo, bar, or baz, or some combination thereof? Maybe configurable? If only baz would show help, would bar and foo get executed? Would the help show before or after foo and bar are executed?).

Luckily, I do not want to accept multiple commands (any sugar available to restrict this? Otherwise I can just attach to an event I presume), although this is likely a common scenario.

Can this be accomplished with cli-command? If not, what would it take to get it done? If you point me in the right direction, I could see about a PR if you think it's something you'd like to support. It sounds like you have plenty to do here and I don't want to pile on.

Thanks for being so responsive and helpful!

Tangentially, in the example, it appears if ls, get, and set are all listed as top-level commands while in the "Examples" section, they appear to be subcommands. Which is correct?

Chris

[tmpfs]

Ok, well for some reason that example is currently broken. I am looking into it.

The tests are still working as expected with the exact same markdown definition and the application I am working on is behaving as expected with regard to the subcommand structure.

The ls, get and set commands should not be listed on the primary help, but should be displayed for --help conf which also seems to be broken.

What you describe is how it should work and does work as expected with the manual middleware, I will look into why the config example is broken and get back to you.

[tmpfs]

Ok, try it now, interesting issue, maybe I should not be so loose when matching target commands, see the commits:

3d9d24c and 024ac9b

That little re-ordering in the unparsed middleware was what broke the --help <cmd> syntax ;)

Try it now:

./ebin/subcommand/config-subcommand --help
./ebin/subcommand/config-subcommand --help conf
./ebin/subcommand/config-subcommand conf --help

I think this is what you describe and expect, right? This is the intended behaviour.

I will try to enable the manual middleware for this shortly so you get an idea of the dynamic man page generation too, which I personally prefer to the help output.

[tmpfs]

Oh, by the way, currently showing help for a command does not include all global options as you describe. From my perspective this is preferable, although we could add this as a configurable feature if it is something you really feel is important.

Also there is a minor error with the Arguments header being shown even though the conf command has no options.

[boneskull]

Thanks for looking into this. Yes I would prefer having the option to show stuff like "verbose", etc., on each command's "help" page, if it's not too much trouble. Not a high priority.

[tmpfs]

Cool, raise a separate issue for that feature if you would like it.

I have enabled the manual middleware for config-subcommand so you should be able to do help and help conf now to view the man page help output.

[boneskull]

Too awesome. Thanks.

[tmpfs]

The problem with the trailing Arguments header is fixed in 4749e20.

Note that the whole thing with having three headings is for compatibility with help2man although I am planning on making this compatibility optional as I don't really like the format for the output. I have discussed this with the author of help2man and it is unlikely he will accept my patches so the help configuration object will soon get a help2man boolean that will enable/disable help2man compatibility mode.

Also, now the manual middleware is fairly feature complete I am less concerned with help2man compatibility.