[TYPO3-doc] DocBook: Build Chain / Rendering Pipeline

[Fabien Udriot]

>>> Proposition: what do you thing of setting up a domain to test the
>>> build chain?
> I'd say that's still too early. For now, my goal is to have the build
> chain run on all unix-like systems; so I feel it is better when
> everybody tests the build chain locally first. If that works out,
> installing it on a server should be a breeze.

Ok, np. Just an offer! Let wait till we get some more concrete result.


> For actually running the build chain, I'd suggest to use Hudson: It can
> monitor the repositories, trigger the build and move the generated PDFs
> and HTML to somewhere.

Yes, or shall we call it rather Jenkins? ;) Never mind as we have Documentation decoupled from TER 
extensions, it sounds as a good solution for me.


> Furthermore, I think it would be important to think about commenting to
> documentation again. Right now I would favor an approach which loads the
> comments dynamically via AJAX (like on api.jquery.com) from a separate
> backend. Then, we don't need to adjust the DocBook XSL stylesheets so
> heavily, but place the functionality for comments "on top", and would
> just need to include a simple JavaScript file then.

I understand... Having user contributions is a really interesting feature to have. I already heard 
that idea a couple of time. Thinking of php.net, I just find so many answers to my problem within 
the comments. Let make it happen!

We will need a way for linking "user contributions" with the right "documentation page"? Let 
consider that users can let comments at the bottom of every chapter. Probably an extension should 
take care of assembling HTML documentation with the right comments (by Ajax or inline HTML). Anyway 
the HTML from the documentation rendering process will need to be processed before being outputted, 
I guess. Let talk about that later it that is not the good moment for you.

>>> Also, at one point, I would like to incorporate some SXW ->  Docbook
>>> transformation in the system to have the change to migrate the legacy
>>> documentation into Docbook. I have already started a XSL Stylesheet
>>> that does the job. When there will be more code, I can help with that
>>> as well.
> Good Point! That's definitely a great idea -- I'd suggest to put this
> into the "Helpers" part of the Build tools.
> BTW: Isn't that already done in the ter_doc extension? (SXW ->  DocBook
> conversion) -- can't this be extracted and reused?

Oh yes! The XSL stylesheets can be taken over (and certainly can be improved at the same time). I 
even started one XSL sheet to render "SXW" -> "DocBook v5"

One more thing on the top of that. I think we must take into consideration at an early stage 
multi-language support. ATM, not so many manuals are translated but it may change in the future if 
we can provide a consistent environment / support for translation. Maybe already clear in your 
mind... but just to mention it.

Looking forward to seeing / testing some progress here.

Fb.