>> DocBook is an XML standard. So - in theory - it's "trivial" to make it
>> do what you want.
>>
>> ...in reality, I found it hellishly difficult to change even the tiniest
>> detail about it. Perhaps it would be simpler to rewrite the XSLT from
>> scratch rather than try to figure out how it works.
>
> Right, because RTFMing is impossible...

Most things to do with XML are hard. For whatever reason, XML is 
absurdly overcomplicated, considering what it actually does.

It took me hours of Google searching just to figure out how to make 
DocBook allow me to write character entities. (The manual says it works 
already... Oh, wait, that's for DocBook v4. OK, so how do you make it 
work for v5? Oh yeah, we removed that feature. Great, so how do I turn 
it back on?) I got there eventually, but it was a hell of a lot of work.

Similar fun with XInclude. The manual tells you that XInclude is a great 
way to make modular documents - and so much better than the old entity 
workaround we used to recommend you use. Except, you know what? My XML 
validator and my XSLT processor both POINT-BLANK INGORE any and all 
XInclude declarations. Isn't that wonderful?

>> And maybe, just
>> maybe, the XML-FO processor I'm using just can't be convinced to produce
>> nice output.
>
> Your problem, is that you do not like the default CSS used by your
> docbook editor, not that it can't be convinced to produce nice output.

I don't have a "DocBook editor", I have a text editor with a vague 
understanding of XML. And then I have various command-line tools which, 
after about a day of research, I was able to convince to produce PDF 
output. Fortunately, all of this knowledge can be embedded into scripts. ;-)

> The problem is not with the tool. The problem is with what you're
> telling your tool to do (or not telling it to do). As I said in my other
> response, any word processor younger than you is able to print crisp
> Arial 16pts or justify text properly.

Yes, but can it render the chapter titles in a blue box with rounded 
corners and a fuzzy drop-shadow? Probably not.

> Your current manual looks impressive? You like its look? Then recreate
> the same thing with something you're familiar with, if you can't wrap
> your head around InDesign, or DocBook.

As I say, I can't actually put my finger on exactly what it is about the 
current manual that makes it look so good. It probably isn't any one 
particular thing, it's the cumulative total of many, many small things...

> But the more important thing is - as you mention - the quality of the
> content. Start by writing good content in Notepad (or vi, or gedit, or
> whatever) so that you can focus on the content.
>
> Then import that text into some document formatting tool and apply the
> styles you have chosen to it.

Whilst I agree wholeheartedly, if we write a whole bunch of content as 
(say) TeX input and then decide that actually our tool of choice wants 
XML (or vice versa)...

That's kind of why I'd like to pin down exactly what tool we're going to 
use. Once we start the rewrite, I only want to do it once.

Still, I could sit down and look at the high-level document structure - 
that's very easy to change for any tool.

Post a reply to this message