[TYPO3-doc] DocBook: sample reference file

[François Suter]

Hi,

> I think it would really be a good idea to explicitly write down
> usecases, where the tsref is needed, so that we can pin down all the
> requirements. Maybe we can have a little brainstorming in this list?

Sure we can :-)

> I also have a question about the format the reference will be maintained
> in. Will this be docbook?

What we arrived at during T3DD10 was that the structure we needed could 
not be achieved with DocBook. Now that I dug deeper into DocBook I think 
that something could be achieved, but I must say that - when looking 
again at the diagram Stephan reminded me/us about in his post - I'm not 
so convinced, for the reasons you mention below:

> Because for generating the XML file for the t3editor codecompletion, it
> would be kind of tedious and error-prone to parse the docbook file (e.g.
> you have to rely on the correct order of refentry tags to get type and
> description (or you have to parse the text inside refsection/title)).

Indeed there may not be enough structure in the DocBook reference. OTOH 
given the structure that we envisioned at T3DD10, it seems possible to 
generate the DocBook structure that I submitted here for discussion.

> I know that at t3dd10 we talked about having the tsref in a relational
> database, but I don't remember what were the disadvantages of this
> approach. Because Stephan and I recently talked about making the first
> step towards an online tsref by writing an extbase extension that can
> display an HTML version of the tsref. It would also be easily possible
> by generating docbook and codecompletion xml formats by using another
> fluid template. But this would most simply be based on db records,
> maintainable in the TYPO3 backend.

We talked about that, yes. I think the conclusion was that the most 
important thing to have was the XML reference itself. That this could be 
generated using database-bound data is another topic that can come 
afterwards. That being said the big advantage I see in having a XML 
reference (be it DocBook or some other XML structure) is that patches 
can easily be submitted for it, making it possible to implement new 
features in TYPO3 while at the same time also submitting a documentation 
update patch. I do think that maintenance is easier with text-based data 
that with database-based data. Also it would follow the same logic as 
the rest of the documentation.

Cheers

-- 

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