feat: expose meta variables for custom renderers

[ematipico]

Hi,

I hope this contribution will be welcome! I need to create a custom renderer for the bpaf command-line; however, the internals are not exposed, so I submitted a PR to expose them.

I used a coding agent to understand what's needed and what needs to be exposed. I reviewed the comments and tweaked them a little bit.

Please let me know if this PR is acceptable!

I tested these changes, and it seems that all the metadata needed for custom renderers are all in place.

[pacak]

I need to create a custom renderer for the bpaf command-line

Please tell me more about it :) I'm working on 0.10 and want to make sure it's easy to customize stuff there.

[ematipico]

Two reasons:

• clap allows you to extract the metadata of a command. With this, third-party users can create different outputs and publish crates. See, for example, clap-markdown
• This is the CLI reference for the Biome CLI: https://biomejs.dev/reference/cli/#command-summary . As you can see, it's very long (it's also a big CLI), and its output is more crafted for people accustomed to CLIs. I wanted to change that. Also, I wanted to change a few things, like having only the global flags printed, so I can reduce the amount of info. I also want to properly render the examples with Markdown code blocks, and more.

[pacak]

I see.

So right now I'm working on 0.10. It's a rewrite where I kept only tests and the derive macro. At this moment it's feature complete and all the tests are passing. External API is 95% compatible. Got rid of "positional must be on the right" restrictions, added real global and local flags, etc. Should be faster too. What's missing is all the user facing documentation. I could probably hack something fast but I want to revisit it as well, there's a few things I don't like in the current one.

About your changes...
Meta is gone, replaced by this trait, every parser implements it:

pub trait Visitor<'a> {
    fn item<'t>(&mut self, item: Item<'a, 't>);
    fn identify(&self) -> VKind;
    fn push_group(&mut self, group: VisitGroup);
    fn pop_group(&mut self);
}

Item is roughly what it is right now. {push,pop}_group is And/Or, etc. Info is mostly the same, except help_arg, version_arg are handled differently.

This is public API. I'll probably need to add AsRef<str> for Metadata, but what your pull request does - it's already there.

Doc is gone, replaced by strings carrying ANSI sequences. This way you can have styled info in help/description without having to deal with allocating stuff.

markdown/manpage generators now use all those goodies.

Right now I'm trying to move everything into the right place so exports look clean, then will start looking into updating the documentation.

Depending on how urgent your documentatio update is - I can probably make bits you want public, or you can wait a bit and start experimenting with early version of 0.10 - once I'm happy with the exports I'll push something. Waiting will save you having to rewrite it I guess.

[ematipico]

It's not urgent, I can wait. Looking forward to it!