Mdoc(7) – semantic markup language for formatting manual pages

I'd rather have a markdown-like notation for the source text itself. I imagine that if it were the norm for Unix-like systems to come with online documentation that were as trivially editable as a set of flat markdown files and also aimed for the benefits of brevity you get from short man pages and the depth of coverage of GNU info (without the pain of navigating due to the info viewer's Emacs-inspired keybindings), then most projects' docs would be far more complete and wouldn't find themselves wanting for contributors to write them.*

I'm totally flummoxed, therefore, by statements that markdown is "abominable" and more poorly designed than DocbBook, whose "syntax encumbers the source code to the point of making it unreadable".

Vanilla markdown is obviously unsuitable as a source language for man pages (unless you're willing to throw out the semantics), but mdoc would do well to take a page from the markdown philosophy. I.e., standardize a set of defacto constructs that resemble the types of formatting that people are already embedding in plain text and—crucially—resembles something that you could conceivably find yourself reading in "raw" rather than "rendered" form.

The idea that mdoc (or any similar macro-based formatting system) is human-readable is something that sounds like a joke, except that I know they're not joking. It may not be roff, but that doesn't mean it isn't still junk.

* I see the proliferation of sites like StackOverflow and Read the Docs as indicators of how the officially anointed docs are coming up short. (There's the ADHD, don't-want-to-RTFM, copy-and-paste brogrammer appeal behind those sites, too, but even accounting for that will show that there's something lacking about TFM.)