[TYPO3-doc] DocBook: sample reference file

[François Suter]

Hi Stephan,

I think we have some misunderstandings, but I guess I have trouble 
spelling out my vision ;-)

> But my concerns are following:
> 1.) We build a docbook manual (which no user asked for -> see use cases)

I think you're seeing things the wrong way here. Of course no user has 
asked for a DocBook manual. But we're talking about basing all of our 
manuals on DocBook and that includes the references (if possible). 
DocBook should be - ideally - the basis from which we do the different 
renderings.

> 2.) We write a transformation script for the t3editor which turns out to
> be harder than expected (more work)

That's a possibility and that's why we're still discussing the topic ;-) 
I would just like to state that all the transformation scripts that we 
write will be just a one-time effort, so maybe to ok if there's some 
extra work at first.

Of course - answering to Christian here - it means that we should be 
pretty disciplined when writing a reference with DocBook, but I think 
that this is manageable, because we won't be many to actually commit 
changes and we can/should be very strict in our reviews.

> 3.) We render an online reference (Straight forward: docbook -> html)
> and it turns out to be quite challenging to get the suitable style,
> formating and url-schema, so the online reference gets not as usable as
> it should (and this is bad- because I think we agree that this is the
> most important use case)
> 4.) We want to have a commenting system for the online tsref, but due to
> the static nature of rendered docbook html, it's hard to get a comment
> plugin on each reference page. Since it's hard, and not "necessary" it
> never gets done.
> 5.) We want to give the community a possibility to contribute examples
> on the online tsref, but due to the static nature of rendered docbook
> html, it's hard to implement. Since it's hard, and not "necessary" it
> never gets done.

I'm answering all these points together because I think they are 
related. Indeed DocBook will be rendered to HTML. Upon rendering any 
book can be split into as many files as we want, based on the XSLT.

Now I don't expect that we will use those HTML files straightaway, 
neither for "normal" manuals nor for references. On the contrary I would 
expect the content of the HTML files included as content inside the page 
being viewed on typo3.org. This would make it perfectly possible to 
attach comments, examples, etc. to the content being viewed. Of course, 
the URL should be as helpful as possible.

To achieve this we will probably need to have some table of contents 
stored in the database. I don't know in detail yet how this could work, 
but it certainly does not seem impossible. It may be quite some work, 
but - as I said already - it's a one-time job and it's worth investing 
some effort in it so that we have a documentation that rocks.

How does that sound?

BTW the 2011 TYPO3 Association budget includes a budget I requested for 
the DocBook migration project. I will communicate more about this in the 
near future, but my idea is that - although most of us contribute 
voluntarily - there may be some tasks which require more work or may be 
less exciting and that's when we could use that budget to actually pay 
for someone's work.

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch