I’ve looked through this thread and Ingo’s presentation, and several things stand out:
* I guess one of the primary issues here is that Groff is GPL, and a BSD distribution wants BSD licenses. That’s valid, if you’re willing to live with the corner-cases. Then again, using something like XHTML with semantic markup (e.g. class=“whatever” attributes in paragraphs or spans) might be the way to go if you don’t want to depend on Groff. Back when I used it, I liked Konqueror’s feature where it would interpret man markup and display it in the browser by entering “man:somepage” in the address bar. It didn’t always get things right, but it was good enough for… oh, about 95% of what I wanted to see. :) * As James points out, people write documentation for other people. Those 5% of pages that choke mandoc use low-level markup to work around limitations of man/mdoc. Taking a SWAG here, I’d guess those pages have a wider audience than average — thus, the authors would want to make sure the presentation is right. * As Ingo mentions (pg 7 of the presentation), man/mdoc has long solved the problem of single-sourcing API-style documentation and (to a lesser extent) quick references. Technical writing has been my primary day job since 1982, and I have to concur. Even before I was an adult, manpages already supported both screen and print output, and graphical tools still have trouble doing that well (at least while providing a comfortable, efficient interface for the writers). * Apropos (pun intended) to looking for references to “socket,” writing that NAME line can be an art form in itself. Not only does it have to describe the program or function, it has to anticipate what keywords people will use to look for it. A rare (unique?) instance where content must double as metadata. Going back to what seems to have triggered this discussion — the use of tables in manpages — I’ve recently come around to the idea that tables are a problem when you’re writing single-source documentation. It was hard enough to get right just for plain-text and print output, but now you have the “three screen problem” (computers, tablets, phones) to solve as well. I’ve been doing a *lot* of eBook formatting in the last few years, and few readers handle tables right. Creative use of hanging paragraphs can replace most tables, and I use the word “creative” deliberately here, but some data cries out for tabular format. Getting people to rewrite their manpages to avoid tables might be difficult, but I doubt it would be as difficult as programmatically turning tbl source into something useful in a large majority of cases. — Larry
