Re: [Groff] .if !dTS - GNU extension?

[Larry Kollar]

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