Kramdown-man: A Kramdown convert for converting Markdown files into man pages | Hacker News Reader

Kramdown-man: A Kramdown convert for converting Markdown files into man pages

github.com

55 pointsthunderbong18 comments

Open articleView on HN

Pandoc can also do this:

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

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

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

Asciidoc as well.

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?

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

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.

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.

See also: `ronn` https://github.com/rtomayko/ronn

...ruby markdown2man

Handy trick to use with this: It's surprisingly easy to add your own custom man pages https://blog.robenkleene.com/2023/10/18/custom-man-pages/

It's almost as if fragments of Markdown are presented as one integrated whole...

https://en.wikipedia.org/wiki/Piltdown_Man

Reply on news.ycombinator.com