Re: [Groff] XML and groff as frontend

[Zvezdan Petkovic]

On Fri, Oct 21, 2005 at 10:23:25AM +0300, Greg 'groggy' Lehey wrote:
> On Thursday, 20 October 2005 at 15:07:32 -0400, Zvezdan Petkovic wrote:
> > Take a look at O'Reilly books (colophon section).  Until recently
> > they all were converted from format X into groff and printed.
> 
> Has this changed?  A while back I looked at their conversion software
> and ported it to FreeBSD (/usr/ports/textproc/gmat).  Unfortunately,
> it's probably no longer buildable; there are some strange kludges in
> there, and once I no longer had to use it, I didn't.

Unfortunately, yes.

The colophon of the recent O'Reilly books indicates that they were
typeset in FrameMaker instead of groff.

I really liked Garamond better than this Birka font they are using now
too. :-)

> > Take a look at books written by W. R. Stevens.  Even the updated
> > editions after his death are done by the new co-authors in groff.
> 
> My books are also written in groff.

Greg, I've seen your books online (I'm a BSD user after all),
but didn't have an opportunity to browse through them and I am not a
proud owner.  It's worth mentioning some other people whose books I do
own that are written in groff (and I'm talking about the recent books
here, not the 80's works):  Brian Kernighan, Marshal Kirk McKusick,
Bjarne Stroustrup, Andrew Tanenbaum.  It seems that _real_ UNIX books
are written in groff. :-)

> 
> > I think that limiting groff to "documentation, memos, letters, and
> > manuals" is not right.
> 
> I didn't see a limitation above.  But I think it's fair to say that
> the majority of books are *not* written in groff.  Even the O'Reilly
> books are usually written in XML DocBook and converted to groff; this
> process is painful enough that I gave up on it.

Correct.  Many scientific books these days seem to be in LaTeX,
and of course everything else is the "other" programs.

I also agree with your assessment of XML DocBook.
I've written a long manual in it, hoping to develop a skill I thought I
will need.  It was a total disappointment.

I have developed a Vim filetype plugin for DocBook that allows me to use
a lot of abbreviations. It opens a second narrow vertical buffer with
all the DocBook keywords (and boy are there many!) so I can pick them up
from there after which it closes and inserts an <open></close> element
of that type.  The plugin also has a set of functions for quick
commenting/uncommenting, enclosing the selected text with a matching
pair of open/close elements, ...

And despite all this, it was a pain I do not want to repeat.
Yes, I even don't feel sorry for that nice plugin collecting the
"electronic dust" on my disk drive.
There's a certain beauty in writing just .LP, .lp, or .P to start a
paragraph. :-)
I do like the content sensitive mark-up, but mdoc approach is much more
sane.

And people who tell me that I should use a graphical front-end for XML
mark-up are equally clueless.  It's not faster at all to move my hand
towards the mouse, find the menu, and choose one of 200 DocBook elements
just to put a word in constant-width font (as it turns out eventually in
PDF, HTML, or any other of DocBook supported formats).  Ridiculous.
It is a fantastic way to lose the concentration during writing.

As I progressed through my manual I diligently tagged each word that
should be tagged, got tired of that and ended up basically writing the
plain ASCII text just to be able to concentrate on writing.

Then I went through a text for proofreading and used my Vim function
(bound to a keystroke) to enclose words in tags selected from the narrow
vertical buffer with DocBook keywords.

> A more interesting question is: can you point to a book written in
> groff (not just converted to and formatted by groff) with serious
> layout problems?

Hmm.  That's a good one.
I think I always recognise books typeset in groff in (La)TeX by a certain
pedantic quality to them.  I think that not only they produce a
high-quality layout, but also the people who prefer to use them are
sensitive to detail.
How many people prepare index for their book in such painstaking detail
as the late Stevens used to (http://www.kohala.com/start/indexing.html).
I doubt that people who choose to write a book in Word bother at all.

Best regards,

        Zvezdan Petkovic