Re: <OK> [Groff] Simplifying groff documentation

[Michael(tm) Smith]

Gunnar Ritter <address@hidden>, 2007-01-03 19:55 +0100:

> As a troff user, my preference would actually be to have
> a collection of XSLT stylesheets, one for each of the
> supported XML input languages, and to have a common troff
> macro set to which all of these are transformed. This is
> because I am interested to use troff as the layout mechanism,
> i.e. as the language in which I specify the visual markup
> aspects.

OK, I can definitely understand that. Anyway, I think if we were
to have a set of stylesheets for converting DocBook to troff, a
lot of the work done in putting those together could be
"repurposed" to create a set of stylesheets for TEI and other
vocabularies. Most XML vocabularies have similar structures for a
lot of the common building blocks -- ordered lists and itemized
lists, footnotes, hyperlinks, etc.

I would guess that there are probably some things that can be done
easily in troff that can't be done easily (or at all) in XSL-FO.
For example, the DocBook stylesheets rely on some custom XSLT
extension functions (written in Java) for some optional features;
one such feature is placement of numbered callouts in files that
are included in output by reference (basically, the use-case is
for adding callouts to program listing, by including-by-reference
of actual code file -- C, Java, Perl, whatever).

dblatex is able to handle placement of the callouts for that case
without relying on any extension functions (because LaTeX itself
already provides support for it).

And just to give another example, ConTeXt provides features for
adding all sorts of useful stuff to PDFs (navigation menus and
such) that XSL-FO has no way of representing.

I'd imagine there might be similar cases where groff can easily
produce certain output that would be difficult or impossible to
do with an XSL-FO toolchain (at least without custom XSLT
extension functions or non-standard extensions to XSL-FO engines).

> For most elements, the stylesheet would actually be quite
> simple; for example, it could just convert <blockquote> to
> .Blockquote. (Another stylesheet could convert a similar
> non-DocBook element to the same troff macro call.)

Yep, I can see that. It's the same basic case as with LaTeX.

> DocBook is most important for the kind of books which have
> been published using troff so far, so it would certainly be
> the appropriate place to start.

You won't get disagreement from me about that :) DocBook does seem
to have become the de facto XML vocabulary used in the free
software community.

But that said, despite all its complexity, the scope of DocBook is
actually quite limited. It's most useful for marking up technical
documention about computer hardware and software. It is much less
useful for marking up things like dissertations and conference
papers (the places where roff and LaTeX are a lot more useful).

Despite that, a lot of people do try to shoehorn dissertations and
such into DocBook markup, even though it's not a very good fit.
It would be good to have a more appropriate XML vocabulary for
those things -- which TEI may actually be for all know (the scope
of TEI is much broader).

  --Mike