[Typo3-typo3org] documentation.typo3.org

[Michael Scharkow]

Robert Lemke wrote:

> Please make sure to read the discussion we had in the DocTeam. Sylvain and I 
> invested more than a day for only discussing and doing research for DocBook. 
> I really like the format, for me it's the ideal solution.

Me thinks so, too. Especially after trying it today for the first time 
with cool results.

> However we came over a few disadvantages which let us decide to not use 
> DocBook in the short run. Two major argument against DocBook:
> 
>    - There doesn't exist a comfortable editor like Open Office Writer. The PHP 
>      project for example recommends using VIM or EMACS for it. DocBook
>      support in Open Office is unusable and programming a TYPO3 BE module
>      which acts as a DocBook editor is too much work

Okay, I will research in that area, but meanwhile: We could offer a 
documentation kickstarter which asks a few questions, offers some input 
fields, and generates a docbook file where you can continue to work on. 
Most doc writers are not stupid and if you offer that frequently used 
items in a kickstarted document, they can copy and paste a lot. This 
way, we can also enforce consistency.


>    - We cannot just convert the existing documentation. The main reason for
>      using DocBook is the symantics we gain. Most of the symantics cannot be
>      guessed automatically, so it would be a semi-automatic process which 
>      takes a long time

We can! I just tried http://www.chez.com/ebellot/ooo2sdbk/ on my own 
extension manual. It worked pretty well, and surely can be customized 
further for our docs. See http://userpage.fu-berlin.de/~scharkow/test3.pdf

I'm really beginning to like this, so I imagine we offer some 
infrastructure for the authors so they can upload their db-xml and have 
it tested/converted, like 
http://www.goshaky.com/goshaky/docbook-online-tool/

Than we accept only zip-Files with the xml and pictures, and build all 
the rest ourselves, including archives for mirroring.

Greetings,
Michael