[TYPO3-doc] DocBook: sample reference file

[François Suter]

Hi Stephan,

> I have to disagree here- personally I don't think that this structure is
> important for TYPO3 extension developers/integrators. (Maybe we need to
> discuss some use cases / target group for the manual). I think that we
> have to really hide the complexity, so TYPO3 beginners are not afraid of
> typoscript any more.
> My experience is that you don't have to know the difference of functions
> and cObjects to use typoscript and build extensions.

I know, you already expressed that view during the T3DD10 workshop ;-)

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 (except maybe for the data types vs. all the rest, 
because that's quite like a programming language anyway). But what we 
are building here is meant to be a comprehensive TypoScript reference. 
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).

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. While the categorization will be visible in the TOC, it won't be 
in the index. When we turn to online rendering, the categorization will 
probably become completely secondary. What will be important is that the 
online version be well searchable, fully cross-linked and has unchanging 
URLs. Maybe there will be some entry screen where the categorization is 
still visible, but it will be mostly irrelevant in that case.

What do you think?

Cheers

-- 

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