[TYPO3-doc] DocBook: migrating existing manuals, the first step

[Thomas Schraitle]

Hi,

Thursday 30 June 2011

> > I've written some XSLT stylesheets[1]...
> 
> I didn't forget what you did ;-)

I know, but maybe others are not that involved. :) Just wanted avoid that 
someone else has to go through the same pain with XSLT (in regard to 
grouping). ;)


> I'm just not sure if and how it applies
> to what I was mentioning, which is about migration existing OpenOffice
> manuals to DocBook. If your XSLT can help, it's great :-)

Well, I don't know about the other manuals. I only played with the FLOW3 
manual so far. The stylesheets are the result of what I've found there.


> [...]
> What is it that you call "bridgeheads".

Bridgeheads are free floating titles with no sub-structure. I found something 
like this in the FLOW3 manual:

  bridgehead: An Important Title
  para ...
  para ...
  figure ...
  bridgehead: Another Important Title
  para ...
  table ...

This is IMHO badly structured as everything is on the sibling axis. The 
previous structure makes XSLT processing VERY hard as you have to use an 
unusual selection of nodes.
One of my stylesheets group the bridgeheads and create a reasonable sect1 
structure (or sect2, depending on the level):

  sect1
    title: An Important Title
    para ...
    para ...
    figure ...
  sect1
    title: Another Important Title
    para ...
    table ...

Of course, the DocBook XSL stylesheets knows bridgeheads and can handle them. 
However, the above recommendation is just a precaution. You don't know what 
you want to do with the XML files in the future. For that reason, it's better 
to use the "usual suspects" (aka elements.) :)

Hope that makes it clearer. :) Oh, and by the way: Enjoy your holidays!


Cheers,
  Tom