On: Kramdown-man: A Kramdown convert for converting Ma...

[jhvkjhk]

Pandoc can also do this:

https://gpanders.com/blog/write-your-own-man-pages/

[JamesCoyne → jhvkjhk]

scdoc uses syntax that is almost markdown https://man.archlinux.org/man/scdoc.5.en

[njt → JamesCoyne]

scdoc is a great tool. It's written by Drew DeVault (sourcehut) and works great, I've used it in a couple of projects.

Here's the blog entry[1] where he talks about the rationale for writing the tool.

The page mentions that it is inspired by Markdown, but is not actually Markdown because it was designed for HTML.

I'm glad to see more projects in this space.

[1] https://drewdevault.com/2018/05/13/scdoc.html

[stock_toaster → jhvkjhk]

Asciidoc as well.

[arp242 → stock_toaster]

I don't think either pandoc or Asciidoc will have the semantic info that Kramdown-man has, which will be converted to the correct roff tags?

[stock_toaster → arp242]

Not sure. Asciidoc is pretty comprehensive though. Git uses it for man pages too. https://github.com/git/git/tree/master/Documentation

[arp242 → stock_toaster]

It's not that it doesn't work, it's that you lose information. normally a flag would be:

  .Fl x

And an environment variable:

  .Ev VARNAME

Instead of just saying "this text is bold", or just not marking it at all.

Does that matter? Maybe, maybe not. In theory at least "a list of all flags used and referenced in this document" and "list of all env vars references" would pretty useful. In practice so many manpages get this wrong that it just doesn't work half the time, so then it's no longer all that useful for the general case.

Unless AsciiDoc changed a lot since I last looked at it, it doesn't support anything like this.

[nerdponx → arp242]

It's possible to encode arbitrary metadata in AsciiDoc in the form of "roles" (https://docs.asciidoctor.org/asciidoc/latest/text/text-span-... ) or "blocks" (https://docs.asciidoctor.org/asciidoc/latest/blocks/delimite...).

The oddball reStructuredText also has a similar system of "roles" and "directives", but its syntax is kind of painful to use and IMO AsciiDoc is easier to read and write.