> What I meant is writing new pages in a newer language (insert random lightweight text based format, preferably one where the 'see also' part is linkable)
A little bit of manpage history:
Roff has been around since the beginning of Unix (in fact, the group at Bell Labs who developed Unix got funding by convincing managers they could come up with a good typesetting system). Roff supports a variety of macro sets; for a long time, the most common one for manpages was the “man” macros.
In the early 1990s, BSD came up with the “mdoc” macros, which are a significant improvement over the original “man” macros. mdoc is inherently semantic, and allows easy searching and conversion to other formats, including HTML. You can search for based based on function return type or argument type, program authors, include files and environment variables used, and many more. mdoc pages natively support hyperlinking, including links to other manpages, links within the same manpage, and external hyperlinks.
Mdoc is a very pleasant language, and since it’s used in roff you can combine it with other macro sets like tbl (for tables) and eqn (for mathematics). It supports UTF‐8, it can easily be converted to PDF and/or semantic HTML, and provides great searchability. It’s well‐documented and widely supported (mdoc pages are supported out of the box on any system using mandoc or groff for manpages, meaning Linux, OpenBSD, FreeBSD, NetBSD, Mac OS X, Illumos, Minix…).
Okay, I didn't know all that. Perhaps groff is a better language than I was aware of and there is sure something to say for keeping it available.
But is it really all used? I have never heard of searching man pages by e.g. return type (in section 2 or 3 I assume this would be), nor does hyperlinking work (perhaps due to the pager, but still). If only 1% of the people use it, then either it's up to them to maintain it or we just deprecate it in favor of a new system.
And by the way, the new system doesn't have to be only one language, it can be some generic language that other languages can "compile" to if you have the right packages (just like markdown can be parsed to the current man page language).
As for hyperlinks, this of course depends on your output format. less(1) in a terminal doesn’t do hyperlinks. HTML output will, such as in this page: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/...
And a distribution could, for example, configure man(1) to trigger Lynx (or even Firefox) looking at Mandoc’s HTML output.
These toolchains are still being actively developed and improved (semantic search, for example, has only been around for a couple years despite the format theoretically supporting it since the beginning). I try to do my part by contributing manpages to projects that don’t have one, converting to mdoc macros when practical, and explaining the great featureset available. The best part is that it is so widely supported—at worst, mdoc falls back to the manpage infrastructure we have now; deployment of a new toolsuite is not a problem compared to converting to some brand new format. At best, it supports all these great new features, and it does so today!
> I have never heard of searching man pages by e.g. return type (in section 2 or 3 I assume this would be).
I'm not sure what you mean by return type, but if you want to, I think you can section your manpages however you want; i.e. you can have section 1 be 'games' instead of 6 if you want to, it just makes installing manpages more difficult.
A little bit of manpage history:
Roff has been around since the beginning of Unix (in fact, the group at Bell Labs who developed Unix got funding by convincing managers they could come up with a good typesetting system). Roff supports a variety of macro sets; for a long time, the most common one for manpages was the “man” macros.
In the early 1990s, BSD came up with the “mdoc” macros, which are a significant improvement over the original “man” macros. mdoc is inherently semantic, and allows easy searching and conversion to other formats, including HTML. You can search for based based on function return type or argument type, program authors, include files and environment variables used, and many more. mdoc pages natively support hyperlinking, including links to other manpages, links within the same manpage, and external hyperlinks.
Mdoc is a very pleasant language, and since it’s used in roff you can combine it with other macro sets like tbl (for tables) and eqn (for mathematics). It supports UTF‐8, it can easily be converted to PDF and/or semantic HTML, and provides great searchability. It’s well‐documented and widely supported (mdoc pages are supported out of the box on any system using mandoc or groff for manpages, meaning Linux, OpenBSD, FreeBSD, NetBSD, Mac OS X, Illumos, Minix…).