[docbook] Loss of faith -- somewhat rantish

["Scot W. Stevenson" <scot at possum dot in-berlin dot de>]

Hello there, 

This might seem to be a rant to some, but after about four months of using 
DocBook, I am having a rather overwhelming sensation of frustration that 
probably could also be classified as a loss of faith. I'm posting this here 
because I am sure that other people have gone through this stage and might 
be able to help with suggestions how to get over this without throwing 
everything out of the window, which is my current urge after spending 
another two hours trying to figure something out that I think should be 
trivial.

My problem is not so much the process of writing texts themselves -- I loved 
LaTeX and love that part of DocBook, love being able to just type 
"<programlisting>" when editing a text with vim and have things come out 
nice and grey in HTML. This is simple, this is clean, this is how things 
should be. This part of life is good and is why DocBook is great.

What is killing DocBook for me is all the -- pardon my French here, I've had 
a rough morning -- crap that you have to go through in the first few lines 
to get the text off of the ground. The "header lines" as I call them are as 
incomprehensible, complex and brittle as the rest of the setup is elegant. 
It is beyond me what

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
         "http://docbook.org/xml/4.2/docbookx.dtd"; []>

actually does or means, why I have to invoke an URL just to get a article off 
the ground that will never leave my computer as XML in any case, and why 
this need concern me at all anyway. These lines are as full of special 
characters like exclamation points, dashes and square brackets as the markup 
tags themselves are human readable; what the difference between 
"docbookx.dtd" and, say, "docbooky.dtd" is remains a mystery. If I am 
writing a text in German, do I have to replace "EN" by "DE"? Why is there a 
"-" before "OASIS" and not a "+"? If it is a constant part of all DocBook 
texts, why do I have to deal with it at all?

Actually, we even start out with a first line 

    <?xml version="1.0" encoding="ISO-8859-1"?>

where the programs go into hysterics if you put in once space too many, which 
is a pain even though the only language I can even program my name in is 
whitespace-obsessed Python. The "encoding" tag obviously doesn't seem to do 
anything either because the machinery behind DocBook just ate my German 
umlauts anyway when one "drop in" replacement, well, wasn't. Still haven't 
fixed that one, by the way. 

Again, why this line if all DocBook texts use it anyway?

I've tried to understand the basis of this and keep getting to the point 
where the documentation is basically telling me: Go away and learn XML, kid. 
But I am trying to write a text, not deepen my knowledge of basic computer 
formats -- I don't want to have to learn XML, or know what XSL is, or a DTD, 
a stylesheet, or whatever, just to write a bloody two-page article. Just 
give me some default setup, and I'll learn the other stuff if I ever need 
it. 

In short: There is a major discrepancy between the wonderful ease of use of 
the tags in DocBook and the way the user is brutally exposed to all kinds of 
appalling low-level complexity in these header lines, and the complexity is 
ruining the advantages of the markup's simplicity for me.

The tools are not much better. After using the simple and logically named 
"db2html" script to translate my files for a while, I was told that this was 
not so good because, uh, I'm using a DSSSL tool for an XML format (I think). 
So I check Ashley J.S Mills' introduction to DocBook, and he tells me to run 
xsltproc (not quite an intuitive program name in this context, by the way -- 
how about a wrapper?) like this:

  xsltproc file:///path/to/docbook-xsl/xhtml/docbook.xsl in.xml > out.html

Heck if I know where "docbook.xsl" is on my computer; whereis doesn't know 
either, it isn't in any /usr/lib/ or /lib or /usr/local/lib place, and the 
/usr/share/sgml directory where DocBook stuff lives isn't much help either, 
because it is, at first glance, chaotic. Running xsltproc without the file 
entry doesn't work (hangs without an error message, even though it is listed 
as optional in the man page -- nice one). 

Why do I have to know where docbook.xsl is anyway? Can't the system have a 
default place to install things, and a default stylesheet? Why do I have to 
go file-hunting in the depths of my directory tree just for that simple 
article? I'm willing to accept a certain learning curve -- did I mention I 
use vim? -- but this is ridiculous. 

The other thing that makes DocBook very frustating is the documentation. Half 
of the time you read half of the text before you figure out that you were 
reading something on DSSSL when you wanted to know something about XML. The 
books available on paper are way out of date, and O'Reilly tells me that 
there is no current plan to publish a new ("XML") version anytime soon. 

And even the documentation that is there is not very helpful. Marking a part 
of text as bold is a very, very basic operation; I learned that the DocBook 
command for this is <emphasis role="bold"> not through the documentation, 
but by reading another person's DocBook file. These "secret" options make 
you wonder: There seems to be no way to indent a paragraph's first line by 
one tab stop (or whatever), though this is a standard feature required in 
publishing. But can I be sure? I would _love_ this option because I could 
then write prose texts with DocBook, too. 

DocBook is a brilliant idea that could have me writing in nothing else, if 
only the headers and tools would let me. I am at something of a loss why the 
header stuff can't be hidden by default -- put some <style> tag at the 
beginning that will let the user set stuff that is different from the 
default in a human readable form, and run it through a pre-processor if you 
must so that the ugly XML/DSSSL stuff is generated for the down stream 
tools. I don't understand why DSSSL is not just marked "depreciated" to get 
rid of the double documentation; a gradual switch is nice, but running two 
versions in parallel is hell on newbies if you have to actually adopt header 
lines and tools (which you shouldn't have to care about anyway).

I'm going to go take a cold shower for a while, and yes, I do feel somewhat 
better now, thank you. But this is terribly frustrating, and I am getting to 
the point where the good things are not worth the hassle. 

Again, sorry for the rant,
Y, Scot

-- 
                  Our cat likes to do that, too
               Scot W. Stevenson - Zepernick, Germany


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org