Kramdown-man: A Kramdown convert for converting Markdown files into man pages(github.com)
github.com
Kramdown-man: A Kramdown convert for converting Markdown files into man pages
https://github.com/postmodern/kramdown-man
20 comments
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
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:
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.
.Fl x
.Ev VARNAME
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.
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
...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
https://en.wikipedia.org/wiki/Piltdown_Man
[deleted]
throwme_123(3)
https://gpanders.com/blog/write-your-own-man-pages/