Improve parsing and formatting inside after_help

[Agent-Hellboy]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Clap Version

master

Describe your use case

Hi , I am coming from uutils/coreutils#8362
clap_mangen is outputting after_help content as plain text, causing list items to appear inline instead of properly formatted.
https://github.com/clap-rs/clap/blob/583ba4ad9a4aea71e5b852b142715acaeaaaa050/clap_mangen/src/render.rs#L248C15-L248C25

Describe the solution you'd like

Fix suggestions to discuss

• Parse list items (lines starting with - )
• Extract options and descriptions
• Use proper roff formatting (.TP, .B, .I)

I will add a PR.

Alternatives, if applicable

No response

Additional Context

No response

[epage]

@pksunkara at #6088 (comment)

@epage I don't have much context here, but we specifically say that the help text is not markdown, right? IIRC, I had some discussions about this back in the days. Can you please let me know if something changed?

[epage]

Correct, we do not specify the output is markdown.

What we are missing is turning of ANSI escape codes into ROFF. I'm playing around with it but its showing some limitations in roff and anstyle-roff.

[Agent-Hellboy]

Correct, we do not specify the output is markdown.

What we are missing is turning of ANSI escape codes into ROFF. I'm playing around with it but its showing some limitations in roff and anstyle-roff.

could you please explain it in details with some context? and how it's related to the current issue.

[pksunkara]

What we are missing is turning of ANSI escape codes into ROFF.

I am not sure if ROFF has special syntax for display lists. But if it does:

If we implement #5900, Doc comments written in markdown with lists -> ANSI just prints indented list -> ROFF needs to parse it again. In this scenario, isn't it better to pass direct markdown from docstring to generators?

---

Without that decision and implementing #5900 first, I am not sure this issue can be resolved since we don't want to have any custom syntax support for help strings.

[epage]

could you please explain it in details with some context? and how it's related to the current issue.

While ANSI escape codes can't help with bulleted lists, they can help with other forms of formatting.

[epage]

Not mentioned in this thread is that #6088 replaced blank lines with .PP. We do that for long_about but none of our other user-provided text. It likely deserves an issue on its own.