So, any improvements made to man are very much welcomed! I do feel, however, that a new format might be the best way to go - possibly something based loosely on Markdown or (my personal preference) JSON. I feel that if we had a more structured manpage format, we could do a lot more with it. I was hoping in my app, for example, to be able to pull out commands (e.g. enter "ls -lh" and it'll highlight the information for "-l" and "-h".) It is possible (http://explainshell.com/ does it really nicely) but it would be far easier with a nicely structured format.
This is actually already the case. The original man(7) language (actually a set of macros for troff) has been around since the early 70s and was part of Unix since the beginning. It’s a simple language but entirely presentation‐focused, so it’s not helpful for semantic manipulation.
Modern manpages should be written in mdoc(7), another troff macro set that’s both more semantic and more expressive than man(7). mdoc(7) was first developed in 1989 for BSD and has been the standard documentation format there ever since, and is fairly common in Linux software as well (although there’s still a large contingent using the old, non‐semantic man(7) macros).
A lot of mandoc’s power comes from the semantic ability of mdoc(7) manpages, including the ability to search by flags/options/environment variables/whatever, and the ability to convert to semantic HTML5. Ingo didn’t cover so much of that in this talk, but he has in some other talks:
It really shows that you should try to avoid writing C code when possible.