[TYPO3-doc] DocBook: sample reference file

[Christian Kartnig]

Hi all,

Thanks Francois for pointing out the advantages for keeping the 
reference in a file. For the versioning and patching procedure I think 
it would really be the best to have everything in one single file.

> OTOH of course if the DocBook reference were the base, we could live
> with having a single "system", which is a great advantage IMO.

Why is this a great advantage? Because we wouldn't need any 
transformation in this case?
I would go for a tailor made proprietary XML format, similar to what we 
proposed at t3dd10. If we have all we need in their own attributes, it 
can be easily parsed and transformed or as well imported in the database 
the online TSRef extension would use, each time there is an update.

So, here are my usecases:

- as a newbie, I want to search the tsref for some property and learn 
about how and in which context it is used. As a newbie, I also want to 
know about the correct hierarchy of the elements (eg. 
HMENU->TMENU->TMENUITEM) (maybe in a tree?), have a comprehensive 
example of that and a link to some manual/guide/tutorial, where things 
are further explained.

- as an integrator, I want to have a browsable reference to find Objects 
and properties and a short explanation. I also want a formal system of 
datatypes in the type field, not some loose explanations. I also want to 
have a list of Objects in with I can use a given property/function (e.g. 
stdWrap). If something is deprecated, I want to have that explicitly 
marked, so I can instantly see I'm not supposed to use it. Also I want 
to read hand-picked relevant comments by other users that point out 
other aspects and give tips (like on php.net).

- as a developer, I want to have all the things the integrator wants, 
plus technical insight into the implementation of these objects, and a 
link to the code, where this is implemented. Also I might be interested 
in the exact versions the property got introduced/deprecated.

What do you think?

cheers,
Christian