add App::get_long_about

[arxanas]

No description provided.

[pksunkara]

bors r+

[bors]

Build succeeded:

• CI

[epage]

@arxanas could you expand on what your use case is?

I can understand us having getters for everything, I'm just wanting to understand the workflow better for where someone needs get_long_about over something like write_long_help.

[pksunkara]

I would use this in one of the generators I am planning.

[epage]

@pksunkara could you share more? What is this generator? Why does it need this over write_long_help?

[arxanas]

@epage The context is in arxanas/git-branchless#114, specifically at commit arxanas/git-branchless@3454ac9. The objective is to generate man-pages automatically. Actually, there is some documentation which says that clap v3 beta supports this: https://rust-cli.github.io/book/in-depth/docs.html, but I couldn't find the corresponding functionality. Maybe @pksunkara intends to implement it?

For the future reader, this is the workaround I used:

let mut buf = Vec::new();
command
    .clone()
    .help_template("{about}")
    .write_long_help(&mut buf)?;
let long_help = String::from_utf8(buf).expect("Argument help should be UTF-8");
manual = manual.description(long_help);

Notes on my development process:

• The string needs to be preprocessed further to translate into a man page, so writing it to an intermediate buffer isn't helpful.
• It's also not particularly helpful that it writes to std::io::Write instead of std::fmt::Write.
• The write_long_help method was somewhat difficult to discover, as I was expecting a getter like the rest of the methods I was using.
• write_long_help takes a &mut Self for some reason?
• Furthermore, none of the print_help/write_help methods mention the help_template method, which controls the behavior of these methods. I only found that method by chance.

[epage]

Thanks! That helps a lot and is a lot of great feedback!

btw you might find git-config-env of interest which I use in my somewhat-similar git-stack

Actually, there is some documentation which says that clap v3 beta supports this: https://rust-cli.github.io/book/in-depth/docs.html, but I couldn't find the corresponding functionality. Maybe @pksunkara intends to implement it?

I remember this coming up in a discussion on the book but I'm not finding it to see how we resolved it. I remember talk about this back when the book was being created but I missed what happened after that.

write_long_help takes a &mut Self for some reason?

Currently, we use this to generate and store some derived settings. Sometime after 3.0 I'd like to play with alternative ways of handling this.

[pksunkara]

Yeah, I originally intended to have a basic manpage generator for 3.0. But I removed it from the milestone about an year ago.