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.
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.
Not the parent, and I don't hate Ruby or any other language. But one practical problem I have with installable scripts in interpreted languages like Ruby gems, Python/Pipx apps and NPM global scripts is that each one is an isolated silo requiring by an entire runtime. Installing the runtime isn't a big issue as it can be done with the system package manager. But each runtime requires a specific environment (like Python's site-packages) with specific settings that don't mix well with that of other language runtimes. Each one also has a separate package manager that has to be invoked for updates. In my case, there are a dozen package managers - too many to set up and remember. I use a script to update each one in a sequence.
Compiled programs aren't that much problematic. They usually integrate well with system libraries and can be installed unobtrusively into the system (like /usr/local/bin or /opt). Or they can be packaged easily for the system package manager. Dependency issues are solved at compile time and forgotten for the most part. Artifact reuse is also better - even between languages like C++ and Rust. The only trouble I had with packaging compiled programs (for Gentoo) is when the compiled program also had JS modules in it. That was precisely due to having to deal with NPM inside a build sandbox.
You're right about runtimes being a pain. I recall that time my Ruby install got hosed by something, I don't know what, that broke Jekyll. I never figured out what happened, and after spending a lot of a time trying to fix it, I gave up, installed Hugo, converted my sites, and never looked back.
This is a valid point. I’m a big fan of Python the language myself, but packaging and distribution is quite the mess.
I honestly wish we at least got first-class support for adding say “import numpy-1.31” to the code, such that you could safely install multiple versions of a package in parallel in the global PYTHONPATH without issues.
https://gpanders.com/blog/write-your-own-man-pages/