Markdown is semantically less expressive than man's markup. man goes into details like explicitly marking up command's arguments.
You can convert man to Markdown easily using full capabilities of Markdown, but Markdown lacks semantic information to be converted back to fully-features man document.
If we had good man viewers that have consistent level of support, then man would be a better data source format.
Unfortunately, there's no way to know what features man viewers support, and AFAIK no good ways to provide graceful fallbacks. This is most broken with tables and links that have dedicated markup, but are not rendered in common setups.
> Markdown lacks semantic information to be converted back to fully-features man document.
Core Markdown, yes. Pandoc has a fenced div extension that can capture the semantic meaning.
::: Warning :::
This is a warning.
::: Danger
This is a warning within a warning.
:::
:::
Not suggesting that Markdown is the right tool, only that it has extensions to capture semantic meaning. Here are example documents produced using Markdown:
But the various man source formats aren't semantic markup of any particular use. Yeah, you can ensure that all of your arguments are typeset as italic or something, but it's not consistent because there are different source macro packages and they do different things.
If there was useful semantic markup, it'd be great, because you could imagine, for example, tools allowing you to generate commands on the user's behalf. But the man source formats are mostly, at core, typesetting for 70's typesetting machines, not intended for modern reference documentation.
mdoc(7), which is the primary macro set used on BSD systems, is a 90s language (as opposed to a 70s language) with useful semantics that support both hyperlinking and featureful search, both on the web and in the terminal.
But the biggest value of manpages to me is somewhat independent of the underlying format: its quality as documentation. BSD systems have a strong tradition of cohesive usability, including good manpages. A lot of the manpage alternatives I see advertised in Linux circles (such as tldr pages or bro pages) are of little use to me, because OpenBSD manuals are thoughtfully written, clear, concise, complete, and have useful examples. The difference is very noticeable when I try reading manpages for programs I’ve installed from packages, which are often incredibly sparse or incredibly verbose, and lack examples in both cases.
The nifty features that come from the modern language and tooling used by BSD manpages are really just symptomatic of the overall care that BSD communities put into their documentation generally. I wish it were more widespread in the free software world.
You can convert man to Markdown easily using full capabilities of Markdown, but Markdown lacks semantic information to be converted back to fully-features man document.
If we had good man viewers that have consistent level of support, then man would be a better data source format.
Unfortunately, there's no way to know what features man viewers support, and AFAIK no good ways to provide graceful fallbacks. This is most broken with tables and links that have dedicated markup, but are not rendered in common setups.