Markdown Generater

[PurpleBooth]

Hi!

I wrote a little thing that might go quite nicely along with the generators, and I was wondering if I should submit it in a PR.

My problem was that I write a little git hook thingy, and the when you run git mit --help it looks for a manpage. Now troff isn't very accessible to most people so I decided to use Pandoc to generate my manpages.

I solved it by using a generator on build to produce my manpages (well the markdown for them), just like the completion helpers. I guess this could be used for other things too, like keeping README's up to date.

I figure this might be useful to other people who use clap, but I saw loooong discussion on it and so it sounds like it might not be something you want. Give me a shout if you want me to tidy this up (Like... it's not tested at the moment).

https://github.com/PurpleBooth/git-mit/tree/main/mit-build-tools/src/manpage

[CreepySkeleton]

Yeah, we've had several quite lengthy discussions, like that one, and I believe the consensus here is that we don't really want to maintain something like this in this org but we're absolutely open to provide the API necessary to make a tool like that possible to build on top clap.

There's a number of unresolved questions, the main being if the input to --help messages suffices for a manpage generator input? Quite a few people, myself included, believe that manpages are pretty pointless when they're identical to --help messages. They tend to be more descriptive and wordy, therefore they should be written separately from help messages. On the other hand, certain properties, like descriptions for options, requires/conflicts_with relationships and so on can and should be synchronized between --help and manpages. I believe this is the direction such a tool should be moving towards.

Yeah, probably not the answer you were hoping for, but... sorry.

@spacekookie you may be interested.

[PurpleBooth]

No that's cool! I am happy for it to stay a thing I keep for myself script. I hate man pages so much, but this specific use case needs them 🤷‍♀️ so...

Things that would make implementing something like this easier is making sure that it's possible to retrieve more of the details that are set in the app, via getters of some kind. Maybe a visitor pattern might work well too.

[CreepySkeleton]

There's a number of App::get_* methods. If you're still missing something, feel free to file an issue and we'll add a new getter.

[PurpleBooth]

Thanks! I just went through the interface, and I actually found getters for all the things that I need, so I suspect that you've beaten me to it!