>>>> 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.
>>
>
> Convince your boss to buy you this:
> http://shop.oreilly.com/product/9780596805012.do

I sorely doubt that any of that book will say anything whatsoever about 
the toolchain problems I'm struggling with. It'll just be 500 pages 
about the actual DocBook markup itself - which I'm having no problem with.

> But what's so complicated about:
>
> <chapter>
> <title>Lorem ipsum</title>
> <para>dolor sit amet</para>
> </Chapter>

OK, now go re-read what I actually said.

Writing the DocBook stuff itself is easy enough. (That's why I'm looking 
at it in the first place.) Configuring the DocBook XSLT stuff is 
difficult. Trying to make entities work is difficult. Trying to split 
the file into parts is difficult. All the stuff that isn't to do with 
writing the actual textual content just seems really difficult.

>> 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.
>
> http://www.docbook.org/docs/howto/#entities

This is about how to make XSLT not strip off custom entities that you 
personally have defined (e.g., your product's name). It has nothing to 
do with standard entities like  .

> http://www.docbook.org/docs/howto/#faq-authoring-general-entities

This is the *actual* solution. Do you have *any idea* how many Google 
searches it took me to find this exact page?? (Also, why does every 
single webpage related to DocBook take five lifetimes to load?)

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

To what? I'm using the latest versions of the tools recommended from the 
DocBook website! :-P

>>> 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.
>> ;-)
>
> http://www.docbook.org/docs/howto/#editors

OK, so... Emacs, oXygen (which is just a general XML editor) and a 
couple of other XML editors. Doesn't really offer any meaningful 
advantage over any other text editor. And really, this isn't the part 
that's causing trouble in the first place.

>> Yes, but can it render the chapter titles in a blue box with rounded
>> corners and a fuzzy drop-shadow? Probably not.
>
> The fuzzy drop shadow and rounded corners are not part of the CSS
> specification (yet!)

Indeed. That's my point. A tool focused on flashy graphics will have all 
these sorts of capabilities - possibly at the expense of making it 
harder to update the content though. (I say *possibly* - I still haven't 
got to the bottom of what InDesign's actual capabilities may or may not be.)

>> 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)...
>
> Which is why you shouldn't write it with ANY output format or tool in
> mind. Think a big README.TXT

Sure. But the final thing is going to need markup. And I don't really 
want to take a huge document and completely redo it to insert that 
markup. It's much easier to insert markup as you write the thing in the 
first place...

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

Well then that's something productive I can actually go work on.

Post a reply to this message