[TYPO3-doc] DocBook: sample reference file

[Christian Kartnig]

Hi Francois!

> Now this distinction does not need to be visible to the reader/user. If
> you think about a straightforward rendering as a book (or book-like
> structure), readers may use the table of contents or more probably the
> index.

I agree with you. I think it's a good idea to preserve the 
categorization, but offer a view where it's possible for newbies to find 
some object without knowing which category it belongs to.

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?

I also have a question about the format the reference will be maintained 
in. Will this be docbook?
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)).

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.

What do you think?

best regards,
Christian