[TYPO3-doc] DocBook: sample reference file

[Stephan Petzl]

Am 21.02.11 21:39, schrieb François Suter:
> I know, you already expressed that view during the T3DD10 workshop ;-)
>
yes, unfortunately I forgot a quite big part of our conversation :/

> I partly agree with you.
>
> There's a real difference between data types, functions and the various
> categories of objects. However I agree that this is rather insignificant
> to newcomers to TYPO3 ....
IMO not only newcomers.

> But what we
> are building here is meant to be a comprehensive TypoScript reference.
Yes I really understand that we don't want to loose information, by 
simply throwing it away...

> To achieve this it makes sense IMO to differentiate those various types
> of elements in various ways (e.g. by grouping them into DocBook parts
> and by including this distinction in the id naming schema).
>
I would really like think about usecases here, because it is not clear 
to me (maybe I forgot), why we have to transfer this complex structure 
of a historically grown typoscript reference in another not-so-simple 
docbook structure. I'm totally OK with docbook, but I don't think we 
will have to transfer everything.
Personally I would be far more happy with the structure we developed 
during DD2010 (Second draft of the new structure):

http://wiki.typo3.org/DocTeam/Online_TSRef

Benefits:
- AFAIK no information will get lost
- can be easily implemented as TYPO3 extension
- can be easily transformed to other formats

For me the main target groups / use cases are:
1) TYPO3 newcomers (who do their first website)
   Usecases:
   1.1) wants to have a step by step tutorial as website, how to do a 
basic page with typoscript
   1.2) wants 1.1 as printable documentation for reading while lying on 
the sofa
   1.3) wants to have a desciption about cObjects, functions and their 
properties on the web

2) extension developers (who maybe did 1-10 extensions)
   Usecases:
   2.1) wants to have a desciption about cObjects, functions, conditions 
and their properties on the web

3) core members (who know internal rendering stuff of TYPO3)
   Usecases:
   3.1) wants to have a desciption about cObjects, functions, conditions 
and their properties on the web
   3.2) wants to know some of the internal rendering process of TYPO3


Did I forget anything?

-- 
Best Regards
Stephan Petzl
http://www.ajado.com