[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Loss of faith -- somewhat rantish
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]