[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Groff] .if !dTS - GNU extension?
From: |
Larry Kollar |
Subject: |
Re: [Groff] .if !dTS - GNU extension? |
Date: |
Tue, 03 May 2016 14:18:10 -0400 |
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