Markdown to Roff#6392
Conversation
|
Note that on #3354, I said the next steps for markdown handling were to create a new issue. Our contrib guide pushes for PRs to be reserved for when a general design is accepted. As this isn't ready yet, I'll move this to a draft. |
Sounds good, thanks for the quick response. Just to clarify, are you aiming to create the issue or do would you like me to kick it off? Sorry, again. I had started the work, before properly reading the guidelines – but hopefully it helps drive the conversation 😊 |
|
If you are interested, feel free to create an issue. Please remember to orient it around the end problem being resolved. |
FintanH
force-pushed
the
feat/mangen-markdown-to-roff
branch
3 times, most recently
from
15ced34 to
1e5a8cd
Compare
Extract the current verbatim text-to-roff behavior into a dedicated plain module with to_roff and to_roff_inline functions. This prepares for an alternative markdown-aware implementation behind a feature flag.
Replace hand-inlined roman(line) loops in render.rs with calls to plain::to_roff and plain::to_roff_inline. No output changes.
Add pulldown-cmark as an optional dependency gated by a new 'markdown' feature flag, enabled by default.
Add markdown::to_roff_inline which converts inline markdown formatting to roff: bold, italic, code-as-bold, links, and autolinks.
Add markdown::to_roff which converts full markdown to roff block structure: paragraphs, headings, lists, code blocks, blockquotes, and rules.
render.rs now imports to_roff and to_roff_inline from the markdown module when the 'markdown' feature is enabled (default), falling back to the plain module otherwise. Added cfg-gated plain snapshots for basic and quoting tests so both feature configurations pass.
Add end-to-end snapshot test exercising markdown-to-roff conversion across about, long_about, option help, and after_help. Only runs with the 'markdown' feature enabled.
Add CHANGELOG entry for the new markdown feature flag and pulldown-cmark-powered help text rendering. Add README section showing supported markdown formatting and how to disable it.
FintanH
force-pushed
the
feat/mangen-markdown-to-roff
branch
from
1e5a8cd to
233269f
Compare
2 participants
I have jumped the gun a bit, after commenting here #3354 (comment), but I'm hoping the changes are a clear improvement to
clap_mangen🙏The main idea behind the PR is that Rust documentation is generally written as markdown, and since
clap_mangenis converting to ROFF, which also has ways to mark up text, then there should be a way to convert some of the doc comments into marked up ROFF.I opted to go for https://github.com/pulldown-cmark/pulldown-cmark which has the highest all-time downloads when searching "markdown" on crates.io (once you've scrolled past the
pestcrates :)).To make this changeset more incremental, I decided to approach it with a feature flag
markdown. The first commits refactor the existing code to maintain the "plain" text output. The next set of commits introduce the markdown conversion toRoff. Then the feature flag is introduced, including it in the default set; which can be up for debate! The final set of commits are integration testing and including this feature in the documentation.I was able to test it on an example in the
heartwoodrepository (that I mentioned in the repository) and here is the before and after:Before:
After:
Let me know if there is anything else I can help with for you to review the changes, or if there's any changes I should make 😊