And the markup is quite presentation oriented; much of it is visual rather than structural and thus difficult to translate well to the web
mdoc (man page linked to is from 4.4BSD, around 1994) has been a thing for a couple of decades now. Many notable *NIX has moved to mdoc – OpenBSD, FreeBSD, NetBSD, illumos; notably missing macOS and most Linux distributions. If you’ll take a look at it, it can encode a lot of semantic information.
For one reason or another, the GNU project seems to vehemently resist the idea of using mdoc, however; the original man macros indeed do have this problem. As do all * to man page converters because they can’t know the semantic information required by mdoc, after all, as well as people being simply unaware of mdoc. mdoc works just fine with groff on Linux.
And of course, because people new to writing man pages will copy what they see in the ecosystem they’re in (which is GNU on Linux or macOS in many cases), the man macros will continue getting copied. Or they don’t bother to learn anything at all and rely on converters and manual formatting. If they even bother to write a man page at all, these days.
Much of the man page corpus is just plain wrong. Many changed the code and never bothered to change the documentation. One can easily get misled.
UNIX/POSIX … is getting massively “bit-rotted” in its old age. Time for different metaphors, possibly maintained by ML to keep them effective and relevant?
I run across examples semi-regularly, and try to report upstream when I find them (some upstreams are easier to report to than others). Mostly I’m pretty happy with manual pages, though.
Just recently, I noticed that pngcrush(1) on Debian is missing the newish -ow option. Upstream doesn’t ship a manpage at all, so Debian wrote one, but it doesn’t stay in sync automatically. Therefore I should probably report this to Debian. Upstream does ship a fairly complete pngcrush -v help text though, so I wonder if the manpage could be auto-synced with that.
I’m pretty sure I’ve reported a bunch of others in the past, but the only example that comes to mind at the moment is that privileges(5) on illumos used to be years out of date, missing some newer privileges, but it was fixed fairly quickly after I reported a bug.
I really want to see documentation generated via machine learning systems. I wouldn’t want to use that documentation for anything, but I’d like to see it.
“This is a summary of the blog post about draining the manual page swamp. The complete blog post is available as a GNU info document.”
mdoc (man page linked to is from 4.4BSD, around 1994) has been a thing for a couple of decades now. Many notable *NIX has moved to mdoc – OpenBSD, FreeBSD, NetBSD, illumos; notably missing macOS and most Linux distributions. If you’ll take a look at it, it can encode a lot of semantic information.
For one reason or another, the GNU project seems to vehemently resist the idea of using mdoc, however; the original man macros indeed do have this problem. As do all
*to man page converters because they can’t know the semantic information required by mdoc, after all, as well as people being simply unaware of mdoc. mdoc works just fine with groff on Linux.And of course, because people new to writing man pages will copy what they see in the ecosystem they’re in (which is GNU on Linux or macOS in many cases), the man macros will continue getting copied. Or they don’t bother to learn anything at all and rely on converters and manual formatting. If they even bother to write a man page at all, these days.
Repetitive, irrelevant, and … pointless.
Much of the man page corpus is just plain wrong. Many changed the code and never bothered to change the documentation. One can easily get misled.
UNIX/POSIX … is getting massively “bit-rotted” in its old age. Time for different metaphors, possibly maintained by ML to keep them effective and relevant?
Do you have any examples of outdated manpages? Your comment is awfully vague.
I run across examples semi-regularly, and try to report upstream when I find them (some upstreams are easier to report to than others). Mostly I’m pretty happy with manual pages, though.
Just recently, I noticed that
pngcrush(1)on Debian is missing the newish-owoption. Upstream doesn’t ship a manpage at all, so Debian wrote one, but it doesn’t stay in sync automatically. Therefore I should probably report this to Debian. Upstream does ship a fairly completepngcrush -vhelp text though, so I wonder if the manpage could be auto-synced with that.I’m pretty sure I’ve reported a bunch of others in the past, but the only example that comes to mind at the moment is that
privileges(5)on illumos used to be years out of date, missing some newer privileges, but it was fixed fairly quickly after I reported a bug.I really want to see documentation generated via machine learning systems. I wouldn’t want to use that documentation for anything, but I’d like to see it.