Markdown is not converted to ROFF for man pages

[sylvestre]

see https://manpages.debian.org/unstable/rust-coreutils/rust-test.1.en.html

to reproduce, with https://github.com/uutils/coreutils/pull/5092

make manpages
man target/debug/man/test.1

[tertsdiepraam]

This is probably due to how Debian renders the manpage online if it works locally. Or are lists supposed to be done some other way within manpages?

[microcassidy]

Sorry, I made a mistake and I can now see what the problem is.

I think the issue should be relabelled as a clap_mangen issue as it isn't rendering bullet lists correctly

./coreutils manpage test | sed 's/^\* *\(.*\)/.IP \\[bu]\n\1/' seems to get you closer to what you probably want.

This issue is not exclusive to the test manpage either.

> rg --vimgrep "^\*" man | awk '{print $1}' | cut -d : -f1 | sort | uniq
man/cp.1
man/du.1
man/mknod.1
man/mv.1
man/nl.1
man/pr.1
man/printf.1
man/test.1

Documentation

• groff manual-lists
• man page manual

[microcassidy]

I have closed my PR for the time being as it's probably not an issue with clap_mangen. Someone should verify but the section that @sylvestre referred to that isn't being parsed correctly is completed by the help_section proc macro and our own parser for markdown. This should probably be fixed up instead of using my quick fix.

> rg test.md
src/uu/test/src/test.rs
25:const ABOUT: &str = help_about!("test.md");
39:const AFTER_HELP: &str = help_section!("after help", "test.md");

Related Files

proc macro

• src/uucore_procs/src/lib.rs parser:
• src/uuhelp_parser/src/lib.rs
• ./src/uu/test/test.md

[cakebaker]

Hm, I don't see the connection with uucore_procs and uuhelp_parser. All they do is retrieve some strings from a markdown file (test.md in your example) with a certain structure. And these strings are then passed to clap's Command object with .about() and .after_help().

I think the "problem" is that a string passed to .after_help() is treated as free-form text and so a markdown bullet list loses its meaning and becomes just text. And clap_mangen interprets it later as such as you can see in https://github.com/clap-rs/clap/blob/master/clap_mangen/src/render.rs#L230 .

So I agree with you and I wouldn't call it an issue with clap_mangen. And yes, I think we should fix it properly in our code instead of using a quick fix.

[microcassidy]

Yeah @cakebaker, I agree. It's a little optimistic to hand md to a roff interpreter and expect it to be okay. The parser is currently handing over markdown, which is why I said it's a problem.

[tertsdiepraam]

So I suppose the conclusion is that we write markdown, which we then convert to

• roff for man pages
• HTML for the online docs (this is done already)
• Plain text for the --help flags (like termimad although I don't think that's good enough)

That's definitely some interesting infrastructure to build :)

Edit: I renamed the issue again, hope that describes it better.

[62mkv]

is it still a good first issue @tertsdiepraam ? :)

[tertsdiepraam]

It's an interesting one for sure! You could go for a solution that isn't perfect but only handles itemized lists for instance to make it simpler.