Re: [Groff] Re: Simplifying groff documentation

[Larry Kollar]

> ... I agree with your assessment of *roff and TeX (I used both
> extensively).  However, I did write a 10 page technical
> document (34 with the appendices that simply include the
> files) in DocBook-XML.  I have turned away in disgust and
> never looked back.

I'll use Zvezdan's example here as a jumping-in point, because
it serves to highlight my primary concern here. But before I
start, I think I speak for us all when I say to ESR: welcome
to the groff list, and thanks for the contributions you've made
to the "cause" (and that includes doclifter). But from here on,
I speak for myself unless someone wants to delegate. :-)

I've been doing technical writing in the commercial realm for
about 23 years now; I started with *roff, moved to Word and
then FrameMaker, took a long hard look at XML, and recently
"returned to my roots" because I have become increasingly
dissatisfied with the capabilities of even FrameMaker (easily
the best of the current commercial GUI tools). My experiments
and stabs at working with XML in general leave me fearing it's
a rabbit hole that many technical writers won't dare go down,
and the ones that do will eventually look for a way out.

The problem with using XML for documentation is that it was
designed specifically for machine processing -- and *people*
write documents for *other* people. The human element has been
tripping up XML doctypes, one after another, for quite a while
now. One can mandate DocBook here, or DITA there, but if you
have to *mandate* you've already failed. Success means an
*embrace* -- and HTML is about the only doctype that has ever
been widely embraced rather than endured.

Five years or so ago, back before I moved from Linux to MacOSX,
the Konqueror browser did an impressive job displaying man
pages. I could type a URI like "man:ls" into the address bar
and Konq would display the manpage -- and even recognize the
foo(1) idiom and format it as a link. I don't imagine that the
KDE developers have stood still since then; what might it be
capable of now? And, more to the point, why bother converting
this entire body of documentation to DocBook if there's already
a good way to convert it to cross-linked HTML? Wasn't that the
whole point of this exercise anyway?

Another possibility is that groff itself can do the conversion.
The HTML "driver" has a ways to go yet before being able to
produce beautiful HTML, but what comes out now is close enough
to clean up using some awk scripts and HTML Tidy. So it might
be easier, short- and long-term, to encourage people to add the
-mwww macros to their man pages.

-- Larry