Re: [docbook] Loss of faith -- somewhat rantish

[Tobias Reif <tobiasreif at pinkjuice dot com>]

Scot

> 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.

The grey background is not something that can or should be controlled 
from the source DocBook document.

> This is simple, this is clean, this is how things
> should be. This part of life is good and is why DocBook is great.

This is a default setting of one specific tool, not a feature of DocBook.

> 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.

Document type declarations are a mechanism of XML and DTD; any XML 
document can have one, not just those written in DocBook.

You could just exclude it (obviously you can't use entities defined in 
the DTD then).

If you want to include stuff, perhaps try XInclude.

>     <?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

But yes, it does something.

> because the machinery behind DocBook

Don't confuse a specific tool with the language. There are many tools, 
and one language, and they are separate entities.

> just ate my German
> umlauts anyway when one "drop in" replacement, well, wasn't.

If you found a bug in a tool, file a bug report at that tool's site.

> Still haven't fixed that one, by the way.

Overall, you seem to be thoroughly confused. I suggest to get familiar 
with the concepts of the systems DocBook XML is built on, most 
importantly XML. If you want to write XML, you'll have to learn XML, or 
use some editor making it simple for you.

I don't see the specific problem you describe. Here is an example of 
using UTF-8 encoded characters and numeric character references in the 
source:
http://www.pinkjuice.com/joocs/doc/#Simple_CALS_Table
http://www.pinkjuice.com/joocs/test/output.html (table)

Seems to work just fine for Arabic, Japanese, and Russian. I'm sure it 
works for German too.

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

Because the documents may use different encodings.

If your document is encoded in UTF-8 or UTF-16, you can simply write 
<?xml version="1.0"?>.

So you can leave off the doctype declaration, and the short prolog 
should be no problem.

> 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.

Very true. If you write DocBook XML, and have problems which are related 
to XML concepts and features, then look at the XML spec and perhaps a 
good book.

> 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,

DocBook XML **is** XML. If you don't want to learn XML, you can't write 
DocBook XML by hand.

> 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.

I think there are tutorials which do just that.

Get a template from some tutorial, fill in your text, enter one single 
comandline calling your favourite transformation package, and you're 
done. You don't have to write the XML prolog or document type 
declaration by hand; This was your only complaint so far. (The umlauts 
issue may be none, you didn't elaborate.).

If you want to change the styling of the output, you'll have to learn a 
styling language such as CSS or XSL (XSLT+XSLFO), or find a WYSIWYG editor.

I agree that there are many different things to learn if you want to do 
complex things, but you said you want to write a (simple?) two-page 
article, and you seem to be happy with the default styling your tool 
gives you. In this case, there shouldn't be too many issues, I agree.

> 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.

OpenOffice for example might support DocBook better in the future, if 
you want simple interface to DocBook. You'll probably have less control 
then.

> Why do I have to know where docbook.xsl is anyway?

I'd download the latest version of the DocBook to HTML XSLT package you 
are using, then run the simple commandline you listed.

> And even the documentation that is there is not very helpful. Marking
> a part
> of text as bold is a very, very basic operation;

You can not do that in DocBook, but instead in CSS, XSL, etc.

> I learned that the DocBook command for this is <emphasis role="bold">

This triggers a certain styling in *one specific tool*. It's like a 
proprietary HTML tag which works only in one browser and is not 
specified in the standard.

> 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.

For styling HTML, use CSS. Fo styling print, use XSLT+XSLFO. Both should 
offer what you want (CSS ceratinly does).
DocBook itself doesn't and shouldn't offer design and layout features; 
if you don't agree, then DocBook might not be what you want to use.

> But this is terribly frustrating, and I am getting to
> the point where the good things are not worth the hassle.

I also met many issues while working with DocBook and various DocBook 
tools, and it was and is frustrating at times. And I also think that 
there's room for improvement concering both sides (language and tools).

But you definitely should differentiate between the language and the 
tools, and also between structure+semantics and layout+design; this will 
help you when working with DocBook and will also help you when 
suggesting improvements.

Tobi

--
http://www.pinkjuice.com/


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