Asciidoc as well.

arp242 · on Dec 4, 2023

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 · on Dec 4, 2023

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

arp242 · on Dec 4, 2023

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 · on Dec 4, 2023

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.